diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 1bbf88cc1f9..abd49a0367f 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -972,7 +972,7 @@ See also :ref:`@GlobalScope.typeof`, :ref:`typ :ref:`int` **len** **(** :ref:`Variant` var **)** -Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String`, the element count of any array type or the size of a :ref:`Dictionary`. For every other Variant type, a run-time error is generated and execution is stopped. +Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String` or :ref:`StringName`, the element count of any array type, or the size of a :ref:`Dictionary`. For every other Variant type, a run-time error is generated and execution is stopped. :: @@ -992,7 +992,7 @@ Returns the length of the given Variant ``var``. The length can be the character :ref:`Resource` **load** **(** :ref:`String` path **)** -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`. +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`. This method is equivalent of using :ref:`ResourceLoader.load` with :ref:`ResourceLoader.CACHE_MODE_REUSE`. \ **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. diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 28ab0c65f35..164d3d24547 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -5480,20 +5480,10 @@ Clamps the ``value``, returning a :ref:`Variant` not less than `` var b = clamp(8.1, 0.9, 5.5) # b is 5.5 - - var c = clamp(Vector2(-3.5, -4), Vector2(-3.2, -2), Vector2(2, 6.5)) - # c is (-3.2, -2) - - var d = clamp(Vector2i(7, 8), Vector2i(-3, -2), Vector2i(2, 6)) - # d is (2, 6) - - var e = clamp(Vector3(-7, 8.5, -3.8), Vector3(-3, -2, 5.4), Vector3(-2, 6, -4.1)) - # e is (-3, -2, 5.4) - - var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6)) - # f is (-4, -5, -6) -\ **Note:** For better type safety, use :ref:`clampf`, :ref:`clampi`, :ref:`Vector2.clamp`, :ref:`Vector2i.clamp`, :ref:`Vector3.clamp`, :ref:`Vector3i.clamp`, :ref:`Vector4.clamp`, :ref:`Vector4i.clamp`, or :ref:`Color.clamp`. +\ **Note:** For better type safety, use :ref:`clampf`, :ref:`clampi`, :ref:`Vector2.clamp`, :ref:`Vector2i.clamp`, :ref:`Vector3.clamp`, :ref:`Vector3i.clamp`, :ref:`Vector4.clamp`, :ref:`Vector4i.clamp`, or :ref:`Color.clamp` (not currently supported by this method). + +\ **Note:** When using this on vectors it will *not* perform component-wise clamping, and will pick ``min`` if ``value < min`` or ``max`` if ``value > max``. To perform component-wise clamping use the methods listed above. .. rst-class:: classref-item-separator @@ -7225,7 +7215,7 @@ Converts the given ``variant`` to the given ``type``, using the :ref:`Variant.Ty If the type conversion cannot be done, this method will return the default value for that type, for example converting :ref:`Rect2` to :ref:`Vector2` will always return :ref:`Vector2.ZERO`. This method will never show error messages as long as ``type`` is a valid Variant type. -The returned value is a :ref:`Variant`, but the data inside and the :ref:`Variant.Type` will be the same as the requested type. +The returned value is a :ref:`Variant`, but the data inside and its type will be the same as the requested type. :: diff --git a/classes/class_animationmixer.rst b/classes/class_animationmixer.rst index 6cfc7d39f55..08fcd22daa1 100644 --- a/classes/class_animationmixer.rst +++ b/classes/class_animationmixer.rst @@ -59,47 +59,47 @@ Methods .. table:: :widths: auto - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`_post_process_key_value` **(** :ref:`Animation` animation, :ref:`int` track, :ref:`Variant` value, :ref:`Object` object, :ref:`int` object_idx **)** |virtual| |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`add_animation_library` **(** :ref:`StringName` name, :ref:`AnimationLibrary` library **)** | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`advance` **(** :ref:`float` delta **)** | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`clear_caches` **(** **)** | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`StringName` | :ref:`find_animation` **(** :ref:`Animation` animation **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`StringName` | :ref:`find_animation_library` **(** :ref:`Animation` animation **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Animation` | :ref:`get_animation` **(** :ref:`StringName` name **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`AnimationLibrary` | :ref:`get_animation_library` **(** :ref:`StringName` name **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`StringName[]` | :ref:`get_animation_library_list` **(** **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`get_animation_list` **(** **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :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| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`has_animation` **(** :ref:`StringName` name **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`has_animation_library` **(** :ref:`StringName` name **)** |const| | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`remove_animation_library` **(** :ref:`StringName` name **)** | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`rename_animation_library` **(** :ref:`StringName` name, :ref:`StringName` newname **)** | - +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`_post_process_key_value` **(** :ref:`Animation` animation, :ref:`int` track, :ref:`Variant` value, :ref:`int` object_id, :ref:`int` object_sub_idx **)** |virtual| |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`add_animation_library` **(** :ref:`StringName` name, :ref:`AnimationLibrary` library **)** | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`advance` **(** :ref:`float` delta **)** | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`clear_caches` **(** **)** | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`find_animation` **(** :ref:`Animation` animation **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`find_animation_library` **(** :ref:`Animation` animation **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Animation` | :ref:`get_animation` **(** :ref:`StringName` name **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationLibrary` | :ref:`get_animation_library` **(** :ref:`StringName` name **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName[]` | :ref:`get_animation_library_list` **(** **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_animation_list` **(** **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :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| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_animation` **(** :ref:`StringName` name **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_animation_library` **(** :ref:`StringName` name **)** |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`remove_animation_library` **(** :ref:`StringName` name **)** | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`rename_animation_library` **(** :ref:`StringName` name, :ref:`StringName` newname **)** | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -415,9 +415,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Variant` **_post_process_key_value** **(** :ref:`Animation` animation, :ref:`int` track, :ref:`Variant` value, :ref:`Object` object, :ref:`int` object_idx **)** |virtual| |const| +:ref:`Variant` **_post_process_key_value** **(** :ref:`Animation` animation, :ref:`int` track, :ref:`Variant` value, :ref:`int` object_id, :ref:`int` object_sub_idx **)** |virtual| |const| -A virtual function for processing after key getting during playback. +A virtual function for processing after getting a key during playback. .. rst-class:: classref-item-separator diff --git a/classes/class_animationnodestatemachine.rst b/classes/class_animationnodestatemachine.rst index dc2acc3a16d..b65fd227a20 100644 --- a/classes/class_animationnodestatemachine.rst +++ b/classes/class_animationnodestatemachine.rst @@ -413,9 +413,7 @@ Renames the given animation node. void **replace_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Replaces the given animation node with a new animation node. .. rst-class:: classref-item-separator diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index 1a3594d0430..ced6547a658 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -23,6 +23,8 @@ Description This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. +\ **Note:** Areas and bodies created with :ref:`PhysicsServer2D` might not interact as expected with **Area2D**\ s, and might not emit signals or track objects correctly. + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_area3d.rst b/classes/class_area3d.rst index 9608cf0240d..7e185b2139e 100644 --- a/classes/class_area3d.rst +++ b/classes/class_area3d.rst @@ -23,6 +23,8 @@ Description This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. +\ **Note:** Areas and bodies created with :ref:`PhysicsServer3D` might not interact as expected with **Area3D**\ s, and might not emit signals or track objects correctly. + \ **Warning:** Using a :ref:`ConcavePolygonShape3D` inside a :ref:`CollisionShape3D` child of this node (created e.g. by using the **Create Trimesh Collision Sibling** option in the **Mesh** menu that appears when selecting a :ref:`MeshInstance3D` node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple :ref:`ConvexPolygonShape3D`\ s or primitive shapes like :ref:`BoxShape3D`, or in some cases it may be replaceable by a :ref:`CollisionPolygon3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_array.rst b/classes/class_array.rst index dd4e7fceae5..aab0f02c5d2 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -1047,6 +1047,8 @@ Removes an element from the array by index. If the index does not exist in the a Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``. Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. +Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. + \ **Note:** This method acts in-place and doesn't return a modified array. .. rst-class:: classref-item-separator diff --git a/classes/class_astargrid2d.rst b/classes/class_astargrid2d.rst index ccd712b40c9..81f62ecb279 100644 --- a/classes/class_astargrid2d.rst +++ b/classes/class_astargrid2d.rst @@ -56,6 +56,8 @@ Properties .. table:: :widths: auto + +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ + | :ref:`CellShape` | :ref:`cell_shape` | ``0`` | +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ | :ref:`Vector2` | :ref:`cell_size` | ``Vector2(1, 1)`` | +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+ @@ -250,6 +252,48 @@ The pathfinding algorithm will avoid using diagonals if any obstacle has been pl Represents the size of the :ref:`DiagonalMode` enum. +.. rst-class:: classref-item-separator + +---- + +.. _enum_AStarGrid2D_CellShape: + +.. rst-class:: classref-enumeration + +enum **CellShape**: + +.. _class_AStarGrid2D_constant_CELL_SHAPE_SQUARE: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_SQUARE** = ``0`` + +Rectangular cell shape. + +.. _class_AStarGrid2D_constant_CELL_SHAPE_ISOMETRIC_RIGHT: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_ISOMETRIC_RIGHT** = ``1`` + +Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right. + +.. _class_AStarGrid2D_constant_CELL_SHAPE_ISOMETRIC_DOWN: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_ISOMETRIC_DOWN** = ``2`` + +Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left. + +.. _class_AStarGrid2D_constant_CELL_SHAPE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`CellShape` **CELL_SHAPE_MAX** = ``3`` + +Represents the size of the :ref:`CellShape` enum. + .. rst-class:: classref-section-separator ---- @@ -259,6 +303,23 @@ Represents the size of the :ref:`DiagonalMode` en Property Descriptions --------------------- +.. _class_AStarGrid2D_property_cell_shape: + +.. rst-class:: classref-property + +:ref:`CellShape` **cell_shape** = ``0`` + +.. rst-class:: classref-property-setget + +- void **set_cell_shape** **(** :ref:`CellShape` value **)** +- :ref:`CellShape` **get_cell_shape** **(** **)** + +The cell shape. Affects how the positions are placed in the grid. If changed, :ref:`update` needs to be called before finding the next path. + +.. rst-class:: classref-item-separator + +---- + .. _class_AStarGrid2D_property_cell_size: .. rst-class:: classref-property diff --git a/classes/class_audioeffectcapture.rst b/classes/class_audioeffectcapture.rst index 5fbea618514..94349815bf3 100644 --- a/classes/class_audioeffectcapture.rst +++ b/classes/class_audioeffectcapture.rst @@ -23,7 +23,7 @@ AudioEffectCapture is an AudioEffect which copies all audio frames from the atta Application code should consume these audio frames from this ring buffer using :ref:`get_buffer` and process it as needed, for example to capture data from an :ref:`AudioStreamMicrophone`, implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating point PCM. -\ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. +Unlike :ref:`AudioEffectRecord`, this effect only returns the raw audio samples instead of encoding them into an :ref:`AudioStream`. .. rst-class:: classref-introduction-group @@ -32,8 +32,6 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` -- `Audio Mic Record Demo `__ - .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_audioeffectrecord.rst b/classes/class_audioeffectrecord.rst index 5b9c5aa2547..b8dfb528920 100644 --- a/classes/class_audioeffectrecord.rst +++ b/classes/class_audioeffectrecord.rst @@ -19,11 +19,13 @@ Audio effect used for recording the sound from an audio bus. Description ----------- -Allows the user to record the sound from an audio bus. This can include all audio output by Godot when used on the "Master" audio bus. +Allows the user to record the sound from an audio bus into an :ref:`AudioStreamWAV`. When used on the "Master" audio bus, this includes all audio output by Godot. + +Unlike :ref:`AudioEffectCapture`, this effect encodes the recording with the given format (8-bit, 16-bit, or compressed) instead of giving access to the raw audio samples. Can be used (with an :ref:`AudioStreamMicrophone`) to record from a microphone. -It sets and gets the format in which the audio file will be recorded (8-bit, 16-bit, or compressed). It checks whether or not the recording is active, and if it is, records the sound. It then returns the recorded sample. +\ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. .. rst-class:: classref-introduction-group diff --git a/classes/class_audioserver.rst b/classes/class_audioserver.rst index 2aa1c5e2564..b379ba4e6a7 100644 --- a/classes/class_audioserver.rst +++ b/classes/class_audioserver.rst @@ -289,7 +289,7 @@ Name of the current device for audio output (see :ref:`get_output_device_list` value **)** - :ref:`float` **get_playback_speed_scale** **(** **)** -Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played at half its speed). +Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played at half its speed). See also :ref:`Engine.time_scale` to affect the general simulation speed, which is independent from :ref:`playback_speed_scale`. .. rst-class:: classref-section-separator diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index 4b5dfbecfa8..5de49da36e3 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -479,7 +479,7 @@ enum **TextureFilter**: :ref:`TextureFilter` **TEXTURE_FILTER_NEAREST** = ``0`` -The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR: @@ -487,7 +487,7 @@ The texture filter reads from the nearest pixel only. The simplest and fastest m :ref:`TextureFilter` **TEXTURE_FILTER_LINEAR** = ``1`` -The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: @@ -495,7 +495,7 @@ The texture filter blends between the nearest 4 pixels. Use this when you want t :ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``2`` -The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: @@ -503,7 +503,7 @@ The texture filter reads from the nearest pixel in the nearest mipmap. The faste :ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``3`` -The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera. +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC: @@ -511,7 +511,7 @@ The texture filter blends between the nearest 4 pixels and between the nearest 2 :ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = ``4`` -The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: @@ -519,7 +519,7 @@ The texture filter reads from the nearest pixel, but selects a mipmap based on t :ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = ``5`` -The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_MAX: @@ -3108,7 +3108,7 @@ If ``true``, enables subsurface scattering transmittance. Only effective if :ref - void **set_texture** **(** :ref:`TextureParam` param, :ref:`Texture2D` texture **)** - :ref:`Texture2D` **get_texture** **(** :ref:`TextureParam` param **)** |const| -The texture to use for multiplying the intensity of the subsurface scattering transmitteance intensity. See also :ref:`subsurf_scatter_texture`. Ignored if :ref:`subsurf_scatter_skin_mode` is ``true``. +The texture to use for multiplying the intensity of the subsurface scattering transmittance intensity. See also :ref:`subsurf_scatter_texture`. Ignored if :ref:`subsurf_scatter_skin_mode` is ``true``. .. rst-class:: classref-item-separator diff --git a/classes/class_basis.rst b/classes/class_basis.rst index 8a64d822124..7b6246485bb 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -23,7 +23,7 @@ Contains 3 vector fields X, Y and Z as its columns, which are typically interpre Basis can also be accessed as an array of 3D vectors. These vectors are usually orthogonal to each other, but are not necessarily normalized (due to scaling). -For more information, read the "Matrices and transforms" documentation article. +For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. .. note:: @@ -151,6 +151,10 @@ Operators +-------------------------------+-----------------------------------------------------------------------------------------------------+ | :ref:`Basis` | :ref:`operator *` **(** :ref:`int` right **)** | +-------------------------------+-----------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator /` **(** :ref:`float` right **)** | + +-------------------------------+-----------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`operator /` **(** :ref:`int` right **)** | + +-------------------------------+-----------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`operator ==` **(** :ref:`Basis` right **)** | +-------------------------------+-----------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`operator []` **(** :ref:`int` index **)** | @@ -328,6 +332,25 @@ A negative determinant means the basis has a negative scale. A zero determinant Constructs a pure rotation Basis matrix from Euler angles in the specified Euler rotation order. By default, use YXZ order (most common). See the :ref:`EulerOrder` enum for possible values. + +.. tabs:: + + .. code-tab:: gdscript + + # Creates a Basis whose z axis points down. + var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0)) + + print(my_basis.z) # Prints (0, -1, 0). + + .. code-tab:: csharp + + // Creates a Basis whose z axis points down. + var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f)); + + GD.Print(myBasis.Z); // Prints (0, -1, 0). + + + .. rst-class:: classref-item-separator ---- @@ -340,6 +363,27 @@ Constructs a pure rotation Basis matrix from Euler angles in the specified Euler Constructs a pure scale basis matrix with no rotation or shearing. The scale values are set as the diagonal of the matrix, and the other parts of the matrix are zero. + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis.from_scale(Vector3(2, 4, 8)) + + print(my_basis.x) # Prints (2, 0, 0). + print(my_basis.y) # Prints (0, 4, 0). + print(my_basis.z) # Prints (0, 0, 8). + + .. code-tab:: csharp + + var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f)); + + GD.Print(myBasis.X); // Prints (2, 0, 0). + GD.Print(myBasis.Y); // Prints (0, 4, 0). + GD.Print(myBasis.Z); // Prints (0, 0, 8). + + + .. rst-class:: classref-item-separator ---- @@ -378,6 +422,37 @@ Returns the basis's rotation in the form of a quaternion. See :ref:`get_euler` **operator /** **(** :ref:`float` right **)** + +This operator divides all components of the **Basis**, which inversely scales it uniformly. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_operator_div_int: + +.. rst-class:: classref-operator + +:ref:`Basis` **operator /** **(** :ref:`int` right **)** + +This operator divides all components of the **Basis**, which inversely scales it uniformly. + +.. rst-class:: classref-item-separator + +---- + .. _class_Basis_operator_eq_Basis: .. rst-class:: classref-operator diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 2014cbe6e9d..49b51f4be8e 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -68,19 +68,6 @@ In GDScript, it's possible to create lambda functions within a method. Lambda fu # Prints "Attack!", when the button_pressed signal is emitted. button_pressed.connect(func(): print("Attack!")) -\ **Note:** Methods of native types such as :ref:`Signal`, :ref:`Array`, or :ref:`Dictionary` are not of type **Callable** in order to avoid unnecessary overhead. If you need to pass those methods as **Callable**, use a lambda function as a wrapper. - -:: - - func _init(): - var my_dictionary = { "hello": "world" } - - # This will not work, `clear` is not a callable. - create_tween().tween_callback(my_dictionary.clear) - - # This will work, as lambdas are custom callables. - create_tween().tween_callback(func(): my_dictionary.clear()) - .. note:: There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. diff --git a/classes/class_cameraattributesphysical.rst b/classes/class_cameraattributesphysical.rst index 899ed72d154..a01e3278f4f 100644 --- a/classes/class_cameraattributesphysical.rst +++ b/classes/class_cameraattributesphysical.rst @@ -145,7 +145,7 @@ Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physi - void **set_shutter_speed** **(** :ref:`float` value **)** - :ref:`float` **get_shutter_speed** **(** **)** -Time for shutter to open and close, measured in seconds. A higher value will let in more light leading to a brighter image, while a lower amount will let in less light leading to a darker image. +Time for shutter to open and close, evaluated as ``1 / shutter_speed`` seconds. A higher value will allow less light (leading to a darker image), while a lower value will allow more light (leading to a brighter image). Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. diff --git a/classes/class_cameraattributespractical.rst b/classes/class_cameraattributespractical.rst index 64eeae4e7ef..75c60393919 100644 --- a/classes/class_cameraattributespractical.rst +++ b/classes/class_cameraattributespractical.rst @@ -105,7 +105,7 @@ The minimum sensitivity (in ISO) used when calculating auto exposure. When calcu - void **set_dof_blur_amount** **(** :ref:`float` value **)** - :ref:`float` **get_dof_blur_amount** **(** **)** -Sets the maximum amount of blur. When using physically-based blur amounts, will instead act as a multiplier. High values lead to an increased amount of bluriness, but can be much more expensive to calculate. It is best to keep this as low as possible for a given art style. +Sets the maximum amount of blur. When using physically-based blur amounts, will instead act as a multiplier. High values lead to an increased amount of blurriness, but can be much more expensive to calculate. It is best to keep this as low as possible for a given art style. .. rst-class:: classref-item-separator diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index 4fdd54522d6..778941ff915 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -288,7 +288,7 @@ The **CanvasItem** will inherit the filter from its parent. :ref:`TextureFilter` **TEXTURE_FILTER_NEAREST** = ``1`` -The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering. Useful for pixel art. +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR: @@ -296,7 +296,7 @@ The texture filter reads from the nearest pixel only. The simplest and fastest m :ref:`TextureFilter` **TEXTURE_FILTER_LINEAR** = ``2`` -The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_CanvasItem_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: @@ -304,7 +304,9 @@ The texture filter blends between the nearest four pixels. Use this for most cas :ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``3`` -The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps. +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: @@ -312,7 +314,9 @@ The texture filter reads from the nearest pixel in the nearest mipmap. This is t :ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``4`` -The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_CanvasItem_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC: @@ -320,9 +324,9 @@ The texture filter blends between the nearest 4 pixels and between the nearest 2 :ref:`TextureFilter` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = ``5`` -The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. -\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`TEXTURE_FILTER_NEAREST_WITH_MIPMAPS` is usually more appropriate. +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`TEXTURE_FILTER_NEAREST_WITH_MIPMAPS` is usually more appropriate in this case. .. _class_CanvasItem_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: @@ -330,9 +334,9 @@ The texture filter reads from the nearest pixel, but selects a mipmap based on t :ref:`TextureFilter` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = ``6`` -The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. -\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`TEXTURE_FILTER_LINEAR_WITH_MIPMAPS` is usually more appropriate. +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`TEXTURE_FILTER_LINEAR_WITH_MIPMAPS` is usually more appropriate in this case. .. _class_CanvasItem_constant_TEXTURE_FILTER_MAX: diff --git a/classes/class_canvastexture.rst b/classes/class_canvastexture.rst index 61e53b65180..bf92b2dd98c 100644 --- a/classes/class_canvastexture.rst +++ b/classes/class_canvastexture.rst @@ -21,7 +21,7 @@ Description **CanvasTexture** is an alternative to :ref:`ImageTexture` for 2D rendering. It allows using normal maps and specular maps in any node that inherits from :ref:`CanvasItem`. **CanvasTexture** also allows overriding the texture's filter and repeat mode independently of the node's properties (or the project settings). -\ **Note:** **CanvasTexture** cannot be used in 3D rendering. For physically-based materials in 3D, use :ref:`BaseMaterial3D` instead. +\ **Note:** **CanvasTexture** cannot be used in 3D. It will not display correctly when applied to any :ref:`VisualInstance3D`, such as :ref:`Sprite3D` or :ref:`Decal`. For physically-based materials in 3D, use :ref:`BaseMaterial3D` instead. .. rst-class:: classref-introduction-group diff --git a/classes/class_collisionpolygon2d.rst b/classes/class_collisionpolygon2d.rst index 9ea51ee33b6..1b5918473e4 100644 --- a/classes/class_collisionpolygon2d.rst +++ b/classes/class_collisionpolygon2d.rst @@ -166,6 +166,8 @@ The margin used for one-way collision (in pixels). Higher values will make the s The polygon's list of vertices. Each point will be connected to the next, and the final point will be connected to the first. +\ **Note:** The returned vertices are in the local coordinate space of the given **CollisionPolygon2D**. + \ **Warning:** The returned value is a clone of the :ref:`PackedVector2Array`, not a reference. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index aa5f8e9a898..8cd48f4ff44 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -123,6 +123,8 @@ Theme Properties +-----------------------------------+----------------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`sample_bg` | | +-----------------------------------+----------------------------------------------------------------------------------------+---------+ + | :ref:`Texture2D` | :ref:`sample_revert` | | + +-----------------------------------+----------------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`screen_picker` | | +-----------------------------------+----------------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`shape_circle` | | @@ -736,6 +738,18 @@ Background panel for the color preview box (visible when the color is translucen ---- +.. _class_ColorPicker_theme_icon_sample_revert: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **sample_revert** + +The icon for the revert button (visible on the middle of the "old" color when it differs from the currently selected color). This icon is modulated with a dark color if the "old" color is bright enough, so the icon should be bright to ensure visibility in both scenarios. + +.. rst-class:: classref-item-separator + +---- + .. _class_ColorPicker_theme_icon_screen_picker: .. rst-class:: classref-themeproperty diff --git a/classes/class_compressedcubemap.rst b/classes/class_compressedcubemap.rst index 4a26c7050a0..ad7a5e358d9 100644 --- a/classes/class_compressedcubemap.rst +++ b/classes/class_compressedcubemap.rst @@ -19,7 +19,7 @@ An optionally compressed :ref:`Cubemap`. Description ----------- -A cubemap that is loaded from a ``.ccube`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedCubemap** can use one of 4 compresson methods: +A cubemap that is loaded from a ``.ccube`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedCubemap** can use one of 4 compression methods: - Lossless (WebP or PNG, uncompressed on the GPU) diff --git a/classes/class_compressedcubemaparray.rst b/classes/class_compressedcubemaparray.rst index 4a286e4ea13..b3cf5e83510 100644 --- a/classes/class_compressedcubemaparray.rst +++ b/classes/class_compressedcubemaparray.rst @@ -19,7 +19,7 @@ An optionally compressed :ref:`CubemapArray`. Description ----------- -A cubemap array that is loaded from a ``.ccubearray`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedCubemapArray** can use one of 4 compresson methods: +A cubemap array that is loaded from a ``.ccubearray`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedCubemapArray** can use one of 4 compression methods: - Lossless (WebP or PNG, uncompressed on the GPU) diff --git a/classes/class_compressedtexture2darray.rst b/classes/class_compressedtexture2darray.rst index a2d0381d2e2..53ce44df3da 100644 --- a/classes/class_compressedtexture2darray.rst +++ b/classes/class_compressedtexture2darray.rst @@ -19,7 +19,7 @@ Array of 2-dimensional textures, optionally compressed. Description ----------- -A texture array that is loaded from a ``.ctexarray`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedTexture2DArray** can use one of 4 compresson methods: +A texture array that is loaded from a ``.ctexarray`` file. This file format is internal to Godot; it is created by importing other image formats with the import system. **CompressedTexture2DArray** can use one of 4 compression methods: - Lossless (WebP or PNG, uncompressed on the GPU) diff --git a/classes/class_csgpolygon3d.rst b/classes/class_csgpolygon3d.rst index 37a2c9c44ae..384a440cc0f 100644 --- a/classes/class_csgpolygon3d.rst +++ b/classes/class_csgpolygon3d.rst @@ -348,7 +348,7 @@ When :ref:`mode` is :ref:`MODE_PATH` value **)** - :ref:`PathRotation` **get_path_rotation** **(** **)** -When :ref:`mode` is :ref:`MODE_PATH`, the :ref:`PathRotation` method used to rotate the :ref:`polygon` as it is extruded. +When :ref:`mode` is :ref:`MODE_PATH`, the path rotation method used to rotate the :ref:`polygon` as it is extruded. .. rst-class:: classref-item-separator diff --git a/classes/class_curve2d.rst b/classes/class_curve2d.rst index 881032528dd..a2091861254 100644 --- a/classes/class_curve2d.rst +++ b/classes/class_curve2d.rst @@ -295,18 +295,16 @@ Cubic interpolation tends to follow the curves better, but linear is faster (and :ref:`Transform2D` **sample_baked_with_rotation** **(** :ref:`float` offset=0.0, :ref:`bool` cubic=false **)** |const| -Similar to :ref:`sample_baked`, but returns :ref:`Transform2D` that includes a rotation along the curve, with :ref:`Transform2D.origin` as the point position, :ref:`Transform2D.x` as the sideways vector, and :ref:`Transform2D.y` as the forward vector. Returns an empty transform if the length of the curve is ``0``. +Similar to :ref:`sample_baked`, but returns :ref:`Transform2D` that includes a rotation along the curve, with :ref:`Transform2D.origin` as the point position and the :ref:`Transform2D.x` vector pointing in the direction of the path at that point. Returns an empty transform if the length of the curve is ``0``. :: var baked = curve.sample_baked_with_rotation(offset) - # This will rotate and position the node with the up direction pointing along the curve. + # The returned Transform2D can be set directly. + transform = baked + # You can also read the origin and rotation separately from the returned Transform2D. position = baked.get_origin() rotation = baked.get_rotation() - # Alternatively, not preserving scale. - transform = baked * Transform2D.FLIP_Y - # To match the rotation of PathFollow2D, not preserving scale. - transform = Transform2D(baked.y, baked.x, baked.origin) .. rst-class:: classref-item-separator diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 0664ca4713f..89a9d73ad34 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -237,6 +237,8 @@ Methods +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get` **(** :ref:`Variant` key, :ref:`Variant` default=null **)** |const| | +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_or_add` **(** :ref:`Variant` key, :ref:`Variant` default=null **)** | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has` **(** :ref:`Variant` key **)** |const| | +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_all` **(** :ref:`Array` keys **)** |const| | @@ -374,6 +376,18 @@ Returns the corresponding value for the given ``key`` in the dictionary. If the ---- +.. _class_Dictionary_method_get_or_add: + +.. rst-class:: classref-method + +:ref:`Variant` **get_or_add** **(** :ref:`Variant` key, :ref:`Variant` default=null **)** + +Gets a value and ensures the key is set. If the ``key`` exists in the dictionary, this behaves like :ref:`get`. Otherwise, the ``default`` value is inserted into the dictionary and returned. + +.. rst-class:: classref-item-separator + +---- + .. _class_Dictionary_method_has: .. rst-class:: classref-method diff --git a/classes/class_displayserver.rst b/classes/class_displayserver.rst index 21d52fb258f..7f981b71854 100644 --- a/classes/class_displayserver.rst +++ b/classes/class_displayserver.rst @@ -132,6 +132,8 @@ Methods +-------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`global_menu_get_item_tooltip` **(** :ref:`String` menu_root, :ref:`int` idx **)** |const| | +-------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`global_menu_get_system_menu_roots` **(** **)** |const| | + +-------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`global_menu_is_item_checkable` **(** :ref:`String` menu_root, :ref:`int` idx **)** |const| | +-------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`global_menu_is_item_checked` **(** :ref:`String` menu_root, :ref:`int` idx **)** |const| | @@ -1791,6 +1793,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1818,6 +1823,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1845,6 +1853,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1874,6 +1885,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1901,6 +1915,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1932,6 +1949,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1961,6 +1981,9 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -1984,6 +2007,9 @@ Returns index of the inserted item, it's not guaranteed to be the same as ``inde "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -2007,6 +2033,9 @@ Returns index of the inserted item, it's not guaranteed to be the same as ``inde "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -2028,6 +2057,9 @@ Removes all items from the global menu with ID ``menu_root``. "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). .. rst-class:: classref-item-separator @@ -2229,6 +2261,20 @@ Returns the tooltip associated with the specified index ``idx``. ---- +.. _class_DisplayServer_method_global_menu_get_system_menu_roots: + +.. rst-class:: classref-method + +:ref:`Dictionary` **global_menu_get_system_menu_roots** **(** **)** |const| + +Returns Dictionary of supported system menu IDs and names. + +\ **Note:** This method is implemented only on macOS. + +.. rst-class:: classref-item-separator + +---- + .. _class_DisplayServer_method_global_menu_is_item_checkable: .. rst-class:: classref-method @@ -3105,6 +3151,14 @@ void **tablet_set_current_driver** **(** :ref:`String` name **)** Set active tablet driver name. +Supported drivers: + +- ``winink``: Windows Ink API, default (Windows 8.1+ required). + +- ``wintab``: Wacom Wintab API (compatible device driver required). + +- ``dummy``: Dummy driver, tablet input is disabled. + \ **Note:** This method is implemented only on Windows. .. rst-class:: classref-item-separator diff --git a/classes/class_editorexportplatformios.rst b/classes/class_editorexportplatformios.rst index 87d7574541f..054fb517425 100644 --- a/classes/class_editorexportplatformios.rst +++ b/classes/class_editorexportplatformios.rst @@ -31,6 +31,8 @@ Properties .. table:: :widths: auto + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`application/additional_plist_content` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`application/app_store_team_id` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -48,7 +50,7 @@ Properties +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`application/icon_interpolation` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`application/launch_screens_interpolation` | + | :ref:`String` | :ref:`application/min_ios_version` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`application/provisioning_profile_uuid_debug` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -66,6 +68,10 @@ Properties +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`capabilities/access_wifi` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`capabilities/performance_a12` | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`capabilities/performance_gaming_tier` | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`capabilities/push_notifications` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`custom_template/debug` | @@ -96,28 +102,6 @@ Properties +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`icons/spotlight_80x80` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`landscape_launch_screens/ipad_1024x768` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`landscape_launch_screens/ipad_2048x1536` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`landscape_launch_screens/iphone_2208x1242` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`landscape_launch_screens/iphone_2436x1125` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/ipad_768x1024` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/ipad_1536x2048` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/iphone_640x960` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/iphone_640x1136` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/iphone_750x1334` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/iphone_1125x2436` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`portrait_launch_screens/iphone_1242x2208` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`privacy/camera_usage_description` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary` | :ref:`privacy/camera_usage_description_localized` | @@ -140,8 +124,6 @@ Properties +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`storyboard/use_custom_bg_color` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`storyboard/use_launch_screen_storyboard` | - +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`user_data/accessible_from_files_app` | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`user_data/accessible_from_itunes_sharing` | @@ -156,6 +138,23 @@ Properties Property Descriptions --------------------- +.. _class_EditorExportPlatformIOS_property_application/additional_plist_content: + +.. rst-class:: classref-property + +:ref:`String` **application/additional_plist_content** + +Additional data added to the root ```` section of the `Info.plist `__ file. The value should be an XML section with pairs of key-value elements, e.g.: + +:: + + key_name + value + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorExportPlatformIOS_property_application/app_store_team_id: .. rst-class:: classref-property @@ -252,13 +251,13 @@ Interpolation method used to resize application icon. ---- -.. _class_EditorExportPlatformIOS_property_application/launch_screens_interpolation: +.. _class_EditorExportPlatformIOS_property_application/min_ios_version: .. rst-class:: classref-property -:ref:`int` **application/launch_screens_interpolation** +:ref:`String` **application/min_ios_version** -Interpolation method used to resize launch screen images. +Minimum version of iOS required for this application to run in the ``major.minor.patch`` or ``major.minor`` format, can only contain numeric characters (``0-9``) and periods (``.``). .. rst-class:: classref-item-separator @@ -364,6 +363,34 @@ If ``true``, networking features related to Wi-Fi access are enabled. See `Requi ---- +.. _class_EditorExportPlatformIOS_property_capabilities/performance_a12: + +.. rst-class:: classref-property + +:ref:`bool` **capabilities/performance_a12** + +Requires the graphics performance and features of the A12 Bionic and later chips (devices supporting all Vulkan renderer features). + +Enabling this option limits supported devices to: iPhone XS, iPhone XR, iPad Mini (5th gen.), iPad Air (3rd gen.), iPad (8th gen) and newer. + +.. rst-class:: classref-item-separator + +---- + +.. _class_EditorExportPlatformIOS_property_capabilities/performance_gaming_tier: + +.. rst-class:: classref-property + +:ref:`bool` **capabilities/performance_gaming_tier** + +Requires the graphics performance and features of the A17 Pro and later chips. + +Enabling this option limits supported devices to: iPhone 15 Pro and newer. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorExportPlatformIOS_property_capabilities/push_notifications: .. rst-class:: classref-property @@ -544,138 +571,6 @@ Spotlight icon file on iPad and iPhone (2x DPI). If left empty, it will fallback ---- -.. _class_EditorExportPlatformIOS_property_landscape_launch_screens/ipad_1024x768: - -.. rst-class:: classref-property - -:ref:`String` **landscape_launch_screens/ipad_1024x768** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_landscape_launch_screens/ipad_2048x1536: - -.. rst-class:: classref-property - -:ref:`String` **landscape_launch_screens/ipad_2048x1536** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_landscape_launch_screens/iphone_2208x1242: - -.. rst-class:: classref-property - -:ref:`String` **landscape_launch_screens/iphone_2208x1242** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_landscape_launch_screens/iphone_2436x1125: - -.. rst-class:: classref-property - -:ref:`String` **landscape_launch_screens/iphone_2436x1125** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/ipad_768x1024: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/ipad_768x1024** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/ipad_1536x2048: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/ipad_1536x2048** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/iphone_640x960: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/iphone_640x960** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/iphone_640x1136: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/iphone_640x1136** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/iphone_750x1334: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/iphone_750x1334** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/iphone_1125x2436: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/iphone_1125x2436** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - -.. _class_EditorExportPlatformIOS_property_portrait_launch_screens/iphone_1242x2208: - -.. rst-class:: classref-property - -:ref:`String` **portrait_launch_screens/iphone_1242x2208** - -Application launch screen image file. If left empty, it will fallback to :ref:`ProjectSettings.application/boot_splash/image`. - -.. rst-class:: classref-item-separator - ----- - .. _class_EditorExportPlatformIOS_property_privacy/camera_usage_description: .. rst-class:: classref-property @@ -808,18 +703,6 @@ If ``true``, :ref:`storyboard/custom_bg_color` **storyboard/use_launch_screen_storyboard** - -If ``true``, storyboard launch screen is used instead of launch screen images. - -.. rst-class:: classref-item-separator - ----- - .. _class_EditorExportPlatformIOS_property_user_data/accessible_from_files_app: .. rst-class:: classref-property diff --git a/classes/class_editorexportplatformmacos.rst b/classes/class_editorexportplatformmacos.rst index f0dd193e29a..798c79e2f38 100644 --- a/classes/class_editorexportplatformmacos.rst +++ b/classes/class_editorexportplatformmacos.rst @@ -31,6 +31,8 @@ Properties .. table:: :widths: auto + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`application/additional_plist_content` | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`application/app_category` | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -222,6 +224,23 @@ Properties Property Descriptions --------------------- +.. _class_EditorExportPlatformMacOS_property_application/additional_plist_content: + +.. rst-class:: classref-property + +:ref:`String` **application/additional_plist_content** + +Additional data added to the root ```` section of the `Info.plist `__ file. The value should be an XML section with pairs of key-value elements, e.g.: + +:: + + key_name + value + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorExportPlatformMacOS_property_application/app_category: .. rst-class:: classref-property diff --git a/classes/class_editorimportplugin.rst b/classes/class_editorimportplugin.rst index 06e16c135e4..7f1f051cd21 100644 --- a/classes/class_editorimportplugin.rst +++ b/classes/class_editorimportplugin.rst @@ -154,6 +154,8 @@ Methods .. table:: :widths: auto + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_can_import_threaded` **(** **)** |virtual| |const| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`_get_import_options` **(** :ref:`String` path, :ref:`int` preset_index **)** |virtual| |const| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -191,6 +193,20 @@ Methods Method Descriptions ------------------- +.. _class_EditorImportPlugin_private_method__can_import_threaded: + +.. rst-class:: classref-method + +:ref:`bool` **_can_import_threaded** **(** **)** |virtual| |const| + +Tells whether this importer can be run in parallel on threads, or, on the contrary, it's only safe for the editor to call it from the main thread, for one file at a time. + +If this method is not overridden, it will return ``true`` by default (i.e., safe for parallel importing). + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorImportPlugin_private_method__get_import_options: .. rst-class:: classref-method diff --git a/classes/class_editorinspector.rst b/classes/class_editorinspector.rst index 98b057acd41..07c50c9094e 100644 --- a/classes/class_editorinspector.rst +++ b/classes/class_editorinspector.rst @@ -39,6 +39,8 @@ Properties .. table:: :widths: auto + +----------------------------------------------------+------------------------+-------------------------------------------------------------------------------------------------+ + | :ref:`bool` | follow_focus | ``true`` (overrides :ref:`ScrollContainer`) | +----------------------------------------------------+------------------------+-------------------------------------------------------------------------------------------------+ | :ref:`ScrollMode` | horizontal_scroll_mode | ``0`` (overrides :ref:`ScrollContainer`) | +----------------------------------------------------+------------------------+-------------------------------------------------------------------------------------------------+ diff --git a/classes/class_editornode3dgizmo.rst b/classes/class_editornode3dgizmo.rst index 386ed1a4dc7..42280cd0d77 100644 --- a/classes/class_editornode3dgizmo.rst +++ b/classes/class_editornode3dgizmo.rst @@ -29,6 +29,8 @@ Methods .. table:: :widths: auto + +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`_begin_handle_action` **(** :ref:`int` id, :ref:`bool` secondary **)** |virtual| | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_commit_handle` **(** :ref:`int` id, :ref:`bool` secondary, :ref:`Variant` restore, :ref:`bool` cancel **)** |virtual| | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -88,6 +90,20 @@ Methods Method Descriptions ------------------- +.. _class_EditorNode3DGizmo_private_method__begin_handle_action: + +.. rst-class:: classref-method + +void **_begin_handle_action** **(** :ref:`int` id, :ref:`bool` secondary **)** |virtual| + +.. container:: contribute + + There is currently no description for this method. Please help us by :ref:`contributing one `! + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorNode3DGizmo_private_method__commit_handle: .. rst-class:: classref-method diff --git a/classes/class_editornode3dgizmoplugin.rst b/classes/class_editornode3dgizmoplugin.rst index 864e371402d..80c802252b0 100644 --- a/classes/class_editornode3dgizmoplugin.rst +++ b/classes/class_editornode3dgizmoplugin.rst @@ -38,6 +38,8 @@ Methods .. table:: :widths: auto + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`_begin_handle_action` **(** :ref:`EditorNode3DGizmo` gizmo, :ref:`int` handle_id, :ref:`bool` secondary **)** |virtual| | +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_can_be_hidden` **(** **)** |virtual| |const| | +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -93,6 +95,20 @@ Methods Method Descriptions ------------------- +.. _class_EditorNode3DGizmoPlugin_private_method__begin_handle_action: + +.. rst-class:: classref-method + +void **_begin_handle_action** **(** :ref:`EditorNode3DGizmo` gizmo, :ref:`int` handle_id, :ref:`bool` secondary **)** |virtual| + +.. container:: contribute + + There is currently no description for this method. Please help us by :ref:`contributing one `! + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorNode3DGizmoPlugin_private_method__can_be_hidden: .. rst-class:: classref-method diff --git a/classes/class_editorplugin.rst b/classes/class_editorplugin.rst index e07b9af2433..e47ec3de3fa 100644 --- a/classes/class_editorplugin.rst +++ b/classes/class_editorplugin.rst @@ -956,7 +956,7 @@ Use :ref:`_set_window_layout` and :ref:`_make_visible` called when the editor requests them. If you have declared the methods :ref:`_forward_canvas_gui_input` and :ref:`_forward_3d_gui_input` these will be called too. -\ **Note:** Each plugin should handle only one type of objects at a time. If a plugin handes more types of objects and they are edited at the same time, it will result in errors. +\ **Note:** Each plugin should handle only one type of objects at a time. If a plugin handles more types of objects and they are edited at the same time, it will result in errors. .. rst-class:: classref-item-separator diff --git a/classes/class_editorsettings.rst b/classes/class_editorsettings.rst index 1c51943a532..99de256a8fa 100644 --- a/classes/class_editorsettings.rst +++ b/classes/class_editorsettings.rst @@ -61,6 +61,8 @@ Properties +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`debugger/auto_switch_to_remote_scene_tree` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`debugger/profile_native_calls` | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debugger/profiler_frame_history_size` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`debugger/profiler_frame_max_functions` | @@ -231,6 +233,10 @@ Properties +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`filesystem/external_programs/raster_image_editor` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`filesystem/external_programs/terminal_emulator` | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`filesystem/external_programs/terminal_emulator_flags` | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`filesystem/external_programs/vector_image_editor` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`filesystem/file_dialog/display_mode` | @@ -305,6 +311,8 @@ Properties +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`interface/editor/single_window_mode` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`interface/editor/ui_layout_direction` | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`interface/editor/unfocused_low_processor_mode_sleep_usec` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`interface/editor/use_embedded_menu` | @@ -669,6 +677,18 @@ If ``true``, automatically switches to the **Remote** scene tree when running th ---- +.. _class_EditorSettings_property_debugger/profile_native_calls: + +.. rst-class:: classref-property + +:ref:`bool` **debugger/profile_native_calls** + +If ``true``, enables collection of profiling data from non-GDScript Godot functions, such as engine class methods. Enabling this slows execution while profiling further. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_debugger/profiler_frame_history_size: .. rst-class:: classref-property @@ -1735,6 +1755,48 @@ The program that opens raster image files when clicking "Open in External Progra ---- +.. _class_EditorSettings_property_filesystem/external_programs/terminal_emulator: + +.. rst-class:: classref-property + +:ref:`String` **filesystem/external_programs/terminal_emulator** + +The terminal emulator program to use when using **Open in Terminal** context menu action in the FileSystem dock. You can enter an absolute path to a program binary, or a path to a program that is present in the ``PATH`` environment variable. + +If left empty, Godot will use the default terminal emulator for the system: + +- **Windows:** PowerShell + +- **macOS:** Terminal.app + +- **Linux:** The first terminal found on the system in this order: gnome-terminal, konsole, xfce4-terminal, lxterminal, kitty, alacritty, urxvt, xterm. + +To use Command Prompt (cmd) instead of PowerShell on Windows, enter ``cmd`` in this field and the correct flags will automatically be used. + +On macOS, make sure to point to the actual program binary located within the ``Programs/MacOS`` folder of the .app bundle, rather than the .app bundle directory. + +If specifying a custom terminal emulator, you may need to override :ref:`filesystem/external_programs/terminal_emulator_flags` so it opens in the correct folder. + +.. rst-class:: classref-item-separator + +---- + +.. _class_EditorSettings_property_filesystem/external_programs/terminal_emulator_flags: + +.. rst-class:: classref-property + +:ref:`String` **filesystem/external_programs/terminal_emulator_flags** + +The command-line arguments to pass to the terminal emulator that is run when using **Open in Terminal** context menu action in the FileSystem dock. See also :ref:`filesystem/external_programs/terminal_emulator`. + +If left empty, the default flags are ``{directory}``, which is replaced by the absolute path to the directory that is being opened in the terminal. + +\ **Note:** If the terminal emulator is set to PowerShell, cmd, or Konsole, Godot will automatically prepend arguments to this list, as these terminals require nonstandard arguments to open in the correct folder. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_filesystem/external_programs/vector_image_editor: .. rst-class:: classref-property @@ -2229,6 +2291,18 @@ If ``true``, embed modal windows such as docks inside the main editor window. Wh ---- +.. _class_EditorSettings_property_interface/editor/ui_layout_direction: + +.. rst-class:: classref-property + +:ref:`int` **interface/editor/ui_layout_direction** + +Editor UI default layout direction. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_interface/editor/unfocused_low_processor_mode_sleep_usec: .. rst-class:: classref-property @@ -2485,9 +2559,9 @@ The icon and font color scheme to use in the editor. - **Auto** determines the color scheme to use automatically based on :ref:`interface/theme/base_color`. -- **Dark** makes fonts and icons light (suitable for dark themes). +- **Dark** makes fonts and icons dark (suitable for light themes). Icon colors are automatically converted by the editor following the set of rules defined in `this file `__. -- **Light** makes fonts and icons dark (suitable for light themes). Icon colors are automatically converted by the editor following `this set of rules `__. +- **Light** makes fonts and icons light (suitable for dark themes). .. rst-class:: classref-item-separator diff --git a/classes/class_engine.rst b/classes/class_engine.rst index 632de147e18..438bf0a22c6 100644 --- a/classes/class_engine.rst +++ b/classes/class_engine.rst @@ -228,6 +228,10 @@ If ``false``, stops printing error and warning messages to the console and edito Controls how fast or slow the in-game clock ticks versus the real life one. It defaults to 1.0. A value of 2.0 means the game moves twice as fast as real life, whilst a value of 0.5 means the game moves at half the regular speed. This also affects :ref:`Timer` and :ref:`SceneTreeTimer` (see :ref:`SceneTree.create_timer` for how to control this). +\ **Note:** This does not affect audio playback speed. Use :ref:`AudioServer.playback_speed_scale` to adjust audio playback speed independently of :ref:`time_scale`. + +\ **Note:** This does not automatically adjust :ref:`physics_ticks_per_second`, which means that with time scales above 1.0, physics simulation may become less precise (as each physics tick will stretch over a larger period of engine time). If you're using :ref:`time_scale` to speed up simulation by a large factor, consider increasing :ref:`physics_ticks_per_second` as well to improve physics reliability. + .. rst-class:: classref-section-separator ---- diff --git a/classes/class_gdextension.rst b/classes/class_gdextension.rst index 2b6cf2dfeec..04eec5a7d10 100644 --- a/classes/class_gdextension.rst +++ b/classes/class_gdextension.rst @@ -12,9 +12,25 @@ GDExtension **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -.. container:: contribute +A native library for GDExtension. - There is currently no description for this class. Please help us by :ref:`contributing one `! +.. rst-class:: classref-introduction-group + +Description +----------- + +The **GDExtension** resource type represents a `shared library `__ which can expand the functionality of the engine. The :ref:`GDExtensionManager` singleton is responsible for loading, reloading, and unloading **GDExtension** resources. + +\ **Note:** GDExtension itself is not a scripting language and has no relation to :ref:`GDScript` resources. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`GDExtension overview <../tutorials/scripting/gdextension/what_is_gdextension>` + +- :doc:`GDExtension example in C++ <../tutorials/scripting/gdextension/gdextension_cpp_example>` .. rst-class:: classref-reftable-group @@ -57,7 +73,7 @@ enum **InitializationLevel**: :ref:`InitializationLevel` **INITIALIZATION_LEVEL_CORE** = ``0`` - +The library is initialized at the same time as the core features of the engine. .. _class_GDExtension_constant_INITIALIZATION_LEVEL_SERVERS: @@ -65,7 +81,7 @@ enum **InitializationLevel**: :ref:`InitializationLevel` **INITIALIZATION_LEVEL_SERVERS** = ``1`` - +The library is initialized at the same time as the engine's servers (such as :ref:`RenderingServer` or :ref:`PhysicsServer3D`). .. _class_GDExtension_constant_INITIALIZATION_LEVEL_SCENE: @@ -73,7 +89,7 @@ enum **InitializationLevel**: :ref:`InitializationLevel` **INITIALIZATION_LEVEL_SCENE** = ``2`` - +The library is initialized at the same time as the engine's scene-related classes. .. _class_GDExtension_constant_INITIALIZATION_LEVEL_EDITOR: @@ -81,7 +97,7 @@ enum **InitializationLevel**: :ref:`InitializationLevel` **INITIALIZATION_LEVEL_EDITOR** = ``3`` - +The library is initialized at the same time as the engine's editor classes. Only happens when loading the GDExtension in the editor. .. rst-class:: classref-section-separator @@ -98,9 +114,9 @@ Method Descriptions void **close_library** **(** **)** -.. container:: contribute +Closes the current library. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ **Note:** You normally should not call this method directly. This is handled automatically by :ref:`GDExtensionManager.unload_extension`. .. rst-class:: classref-item-separator @@ -112,9 +128,7 @@ void **close_library** **(** **)** :ref:`InitializationLevel` **get_minimum_library_initialization_level** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the lowest level required for this extension to be properly initialized (see the :ref:`InitializationLevel` enum). .. rst-class:: classref-item-separator @@ -126,9 +140,9 @@ void **close_library** **(** **)** void **initialize_library** **(** :ref:`InitializationLevel` level **)** -.. container:: contribute +Initializes the library bound to this GDextension at the given initialization ``level``. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ **Note:** You normally should not call this method directly. This is handled automatically by :ref:`GDExtensionManager.load_extension`. .. rst-class:: classref-item-separator @@ -140,9 +154,7 @@ void **initialize_library** **(** :ref:`InitializationLevel` **is_library_open** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns ``true`` if this extension's library has been opened. .. rst-class:: classref-item-separator @@ -154,9 +166,9 @@ void **initialize_library** **(** :ref:`InitializationLevel` **open_library** **(** :ref:`String` path, :ref:`String` entry_symbol **)** -.. container:: contribute +Opens the library at the specified ``path``. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ **Note:** You normally should not call this method directly. This is handled automatically by :ref:`GDExtensionManager.load_extension`. .. |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_gdextensionmanager.rst b/classes/class_gdextensionmanager.rst index 9c278824fb3..a8f748f6fc2 100644 --- a/classes/class_gdextensionmanager.rst +++ b/classes/class_gdextensionmanager.rst @@ -12,9 +12,25 @@ GDExtensionManager **Inherits:** :ref:`Object` -.. container:: contribute +Provides access to GDExtension functionality. - There is currently no description for this class. Please help us by :ref:`contributing one `! +.. rst-class:: classref-introduction-group + +Description +----------- + +The GDExtensionManager loads, initializes, and keeps track of all available :ref:`GDExtension` libraries in the project. + +\ **Note:** Do not worry about GDExtension unless you know what you are doing. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`GDExtension overview <../tutorials/scripting/gdextension/what_is_gdextension>` + +- :doc:`GDExtension example in C++ <../tutorials/scripting/gdextension/gdextension_cpp_example>` .. rst-class:: classref-reftable-group @@ -53,7 +69,7 @@ Signals **extensions_reloaded** **(** **)** -Emitted after the editor has automatically reloaded any extensions. +Emitted after the editor has finished reloading one or more extensions. .. rst-class:: classref-section-separator @@ -76,7 +92,7 @@ enum **LoadStatus**: :ref:`LoadStatus` **LOAD_STATUS_OK** = ``0`` - +The extension has loaded successfully. .. _class_GDExtensionManager_constant_LOAD_STATUS_FAILED: @@ -84,7 +100,7 @@ enum **LoadStatus**: :ref:`LoadStatus` **LOAD_STATUS_FAILED** = ``1`` - +The extension has failed to load, possibly because it does not exist or has missing dependencies. .. _class_GDExtensionManager_constant_LOAD_STATUS_ALREADY_LOADED: @@ -92,7 +108,7 @@ enum **LoadStatus**: :ref:`LoadStatus` **LOAD_STATUS_ALREADY_LOADED** = ``2`` - +The extension has already been loaded. .. _class_GDExtensionManager_constant_LOAD_STATUS_NOT_LOADED: @@ -100,7 +116,7 @@ enum **LoadStatus**: :ref:`LoadStatus` **LOAD_STATUS_NOT_LOADED** = ``3`` - +The extension has not been loaded. .. _class_GDExtensionManager_constant_LOAD_STATUS_NEEDS_RESTART: @@ -108,7 +124,7 @@ enum **LoadStatus**: :ref:`LoadStatus` **LOAD_STATUS_NEEDS_RESTART** = ``4`` - +The extension requires the application to restart to fully load. .. rst-class:: classref-section-separator @@ -125,9 +141,7 @@ Method Descriptions :ref:`GDExtension` **get_extension** **(** :ref:`String` path **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the :ref:`GDExtension` at the given file ``path``, or ``null`` if it has not been loaded or does not exist. .. rst-class:: classref-item-separator @@ -139,9 +153,7 @@ Method Descriptions :ref:`PackedStringArray` **get_loaded_extensions** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the file paths of all currently loaded extensions. .. rst-class:: classref-item-separator @@ -153,9 +165,7 @@ Method Descriptions :ref:`bool` **is_extension_loaded** **(** :ref:`String` path **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns ``true`` if the extension at the given file ``path`` has already been loaded successfully. See also :ref:`get_loaded_extensions`. .. rst-class:: classref-item-separator @@ -167,9 +177,7 @@ Method Descriptions :ref:`LoadStatus` **load_extension** **(** :ref:`String` path **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Loads an extension by absolute file path. The ``path`` needs to point to a valid :ref:`GDExtension`. Returns :ref:`LOAD_STATUS_OK` if successful. .. rst-class:: classref-item-separator @@ -181,9 +189,9 @@ Method Descriptions :ref:`LoadStatus` **reload_extension** **(** :ref:`String` path **)** -.. container:: contribute +Reloads the extension at the given file path. The ``path`` needs to point to a valid :ref:`GDExtension`, otherwise this method may return either :ref:`LOAD_STATUS_NOT_LOADED` or :ref:`LOAD_STATUS_FAILED`. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ **Note:** You can only reload extensions in the editor. In release builds, this method always fails and returns :ref:`LOAD_STATUS_FAILED`. .. rst-class:: classref-item-separator @@ -195,9 +203,7 @@ Method Descriptions :ref:`LoadStatus` **unload_extension** **(** :ref:`String` path **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Unloads an extension by file path. The ``path`` needs to point to an already loaded :ref:`GDExtension`, otherwise this method returns :ref:`LOAD_STATUS_NOT_LOADED`. .. |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_geometry3d.rst b/classes/class_geometry3d.rst index 9c9e3442758..111cf738fab 100644 --- a/classes/class_geometry3d.rst +++ b/classes/class_geometry3d.rst @@ -58,6 +58,8 @@ Methods +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`segment_intersects_triangle` **(** :ref:`Vector3` from, :ref:`Vector3` to, :ref:`Vector3` a, :ref:`Vector3` b, :ref:`Vector3` c **)** | +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`tetrahedralize_delaunay` **(** :ref:`PackedVector3Array` points **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -234,6 +236,18 @@ Checks if the segment (``from``, ``to``) intersects the sphere that is located a Tests if the segment (``from``, ``to``) intersects the triangle ``a``, ``b``, ``c``. If yes, returns the point of intersection as :ref:`Vector3`. If no intersection takes place, returns ``null``. +.. rst-class:: classref-item-separator + +---- + +.. _class_Geometry3D_method_tetrahedralize_delaunay: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **tetrahedralize_delaunay** **(** :ref:`PackedVector3Array` points **)** + +Tetrahedralizes the volume specified by a discrete set of ``points`` in 3D space, ensuring that no point lies within the circumsphere of any resulting tetrahedron. The method returns a :ref:`PackedInt32Array` where each tetrahedron consists of four consecutive point indices into the ``points`` array (resulting in an array with ``n * 4`` elements, where ``n`` is the number of tetrahedra found). If the tetrahedralization is unsuccessful, an empty :ref:`PackedInt32Array` is returned. + .. |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_gltfdocument.rst b/classes/class_gltfdocument.rst index 0ee16d8009e..917505eb724 100644 --- a/classes/class_gltfdocument.rst +++ b/classes/class_gltfdocument.rst @@ -284,7 +284,7 @@ Unregisters the given :ref:`GLTFDocumentExtension` Takes a :ref:`GLTFState` object through the ``state`` parameter and writes a glTF file to the filesystem. -\ **Note:** The extension of the glTF file determines if it is a .glb binary file or a .gltf file. +\ **Note:** The extension of the glTF file determines if it is a .glb binary file or a .gltf text file. .. |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_gpuparticles2d.rst b/classes/class_gpuparticles2d.rst index 541020cbb53..b1f43904827 100644 --- a/classes/class_gpuparticles2d.rst +++ b/classes/class_gpuparticles2d.rst @@ -692,6 +692,8 @@ void **emit_particle** **(** :ref:`Transform2D` xform, :ref:` Emits a single particle. Whether ``xform``, ``velocity``, ``color`` and ``custom`` are applied depends on the value of ``flags``. See :ref:`EmitFlags`. +The default ParticleProcessMaterial will overwrite ``color`` and use the contents of ``custom`` as ``(rotation, age, animation, lifetime)``. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_gpuparticles3d.rst b/classes/class_gpuparticles3d.rst index 1266893fc5e..1891fa6e040 100644 --- a/classes/class_gpuparticles3d.rst +++ b/classes/class_gpuparticles3d.rst @@ -843,6 +843,8 @@ void **emit_particle** **(** :ref:`Transform3D` xform, :ref:` Emits a single particle. Whether ``xform``, ``velocity``, ``color`` and ``custom`` are applied depends on the value of ``flags``. See :ref:`EmitFlags`. +The default ParticleProcessMaterial will overwrite ``color`` and use the contents of ``custom`` as ``(rotation, age, animation, lifetime)``. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 56ba0cb75c6..fa6e6e86b99 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -44,6 +44,8 @@ Properties +----------------------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ | :ref:`FocusMode` | focus_mode | ``2`` (overrides :ref:`Control`) | +----------------------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`GridPattern` | :ref:`grid_pattern` | ``0`` | + +----------------------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ | :ref:`bool` | :ref:`minimap_enabled` | ``true`` | +----------------------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ | :ref:`float` | :ref:`minimap_opacity` | ``0.65`` | @@ -409,6 +411,32 @@ enum **PanningScheme**: :kbd:`Mouse Wheel` will move the view, :kbd:`Ctrl + Mouse Wheel` will zoom. +.. rst-class:: classref-item-separator + +---- + +.. _enum_GraphEdit_GridPattern: + +.. rst-class:: classref-enumeration + +enum **GridPattern**: + +.. _class_GraphEdit_constant_GRID_PATTERN_LINES: + +.. rst-class:: classref-enumeration-constant + +:ref:`GridPattern` **GRID_PATTERN_LINES** = ``0`` + +Draw the grid using solid lines. + +.. _class_GraphEdit_constant_GRID_PATTERN_DOTS: + +.. rst-class:: classref-enumeration-constant + +:ref:`GridPattern` **GRID_PATTERN_DOTS** = ``1`` + +Draw the grid using dots. + .. rst-class:: classref-section-separator ---- @@ -469,6 +497,23 @@ The thickness of the lines between the nodes. ---- +.. _class_GraphEdit_property_grid_pattern: + +.. rst-class:: classref-property + +:ref:`GridPattern` **grid_pattern** = ``0`` + +.. rst-class:: classref-property-setget + +- void **set_grid_pattern** **(** :ref:`GridPattern` value **)** +- :ref:`GridPattern` **get_grid_pattern** **(** **)** + +The pattern used for drawing the grid. + +.. rst-class:: classref-item-separator + +---- + .. _class_GraphEdit_property_minimap_enabled: .. rst-class:: classref-property @@ -1010,7 +1055,7 @@ Returns the points which would make up a connection between ``from_node`` and `` :ref:`Dictionary[]` **get_connection_list** **(** **)** |const| -Returns an Array containing the list of connections. A connection consists in a structure of the form ``{ from_port: 0, from: "GraphNode name 0", to_port: 1, to: "GraphNode name 1" }``. +Returns an Array containing the list of connections. A connection consists in a structure of the form ``{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }``. .. rst-class:: classref-item-separator @@ -1141,7 +1186,7 @@ Color of the connection's activity (see :ref:`set_connection_activity` **grid_major** = ``Color(1, 1, 1, 0.2)`` -Color of major grid lines. +Color of major grid lines/dots. .. rst-class:: classref-item-separator @@ -1153,7 +1198,7 @@ Color of major grid lines. :ref:`Color` **grid_minor** = ``Color(1, 1, 1, 0.05)`` -Color of minor grid lines. +Color of minor grid lines/dots. .. rst-class:: classref-item-separator diff --git a/classes/class_graphnode.rst b/classes/class_graphnode.rst index 75aa4747a83..91a0ce19b4a 100644 --- a/classes/class_graphnode.rst +++ b/classes/class_graphnode.rst @@ -80,6 +80,10 @@ Methods +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`get_slot_color_right` **(** :ref:`int` slot_index **)** |const| | +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`get_slot_custom_icon_left` **(** :ref:`int` slot_index **)** |const| | + +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Texture2D` | :ref:`get_slot_custom_icon_right` **(** :ref:`int` slot_index **)** |const| | + +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_slot_type_left` **(** :ref:`int` slot_index **)** |const| | +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_slot_type_right` **(** :ref:`int` slot_index **)** |const| | @@ -98,6 +102,10 @@ Methods +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_slot_color_right` **(** :ref:`int` slot_index, :ref:`Color` color **)** | +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_slot_custom_icon_left` **(** :ref:`int` slot_index, :ref:`Texture2D` custom_icon **)** | + +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_slot_custom_icon_right` **(** :ref:`int` slot_index, :ref:`Texture2D` custom_icon **)** | + +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_slot_draw_stylebox` **(** :ref:`int` slot_index, :ref:`bool` enable **)** | +-------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_slot_enabled_left` **(** :ref:`int` slot_index, :ref:`bool` enable **)** | @@ -367,6 +375,30 @@ Returns the right (output) :ref:`Color` of the slot with the given ---- +.. _class_GraphNode_method_get_slot_custom_icon_left: + +.. rst-class:: classref-method + +:ref:`Texture2D` **get_slot_custom_icon_left** **(** :ref:`int` slot_index **)** |const| + +Returns the left (input) custom :ref:`Texture2D` of the slot with the given ``slot_index``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_GraphNode_method_get_slot_custom_icon_right: + +.. rst-class:: classref-method + +:ref:`Texture2D` **get_slot_custom_icon_right** **(** :ref:`int` slot_index **)** |const| + +Returns the right (output) custom :ref:`Texture2D` of the slot with the given ``slot_index``. + +.. rst-class:: classref-item-separator + +---- + .. _class_GraphNode_method_get_slot_type_left: .. rst-class:: classref-method @@ -487,6 +519,30 @@ Sets the :ref:`Color` of the right (output) side of the slot with t ---- +.. _class_GraphNode_method_set_slot_custom_icon_left: + +.. rst-class:: classref-method + +void **set_slot_custom_icon_left** **(** :ref:`int` slot_index, :ref:`Texture2D` custom_icon **)** + +Sets the custom :ref:`Texture2D` of the left (input) side of the slot with the given ``slot_index`` to ``custom_icon``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_GraphNode_method_set_slot_custom_icon_right: + +.. rst-class:: classref-method + +void **set_slot_custom_icon_right** **(** :ref:`int` slot_index, :ref:`Texture2D` custom_icon **)** + +Sets the custom :ref:`Texture2D` of the right (output) side of the slot with the given ``slot_index`` to ``custom_icon``. + +.. rst-class:: classref-item-separator + +---- + .. _class_GraphNode_method_set_slot_draw_stylebox: .. rst-class:: classref-method diff --git a/classes/class_image.rst b/classes/class_image.rst index 68a47239f37..df3f4342bfd 100644 --- a/classes/class_image.rst +++ b/classes/class_image.rst @@ -275,7 +275,7 @@ OpenGL texture format ``RGBA`` with four components, each with a bitdepth of 4. :ref:`Format` **FORMAT_RGB565** = ``7`` - +OpenGL texture format ``RGB`` with three components. Red and blue have a bitdepth of 5, and green has a bitdepth of 6. .. _class_Image_constant_FORMAT_RF: @@ -497,7 +497,7 @@ Texture format that uses `BPTC ` **FORMAT_ETC2_RA_AS_RG** = ``33`` - +`Ericsson Texture Compression format 2 `__ (``RGBA8`` variant), which compresses RA data and interprets it as two channels (red and green). See also :ref:`FORMAT_ETC2_RGBA8`. .. _class_Image_constant_FORMAT_DXT5_RA_AS_RG: @@ -505,7 +505,7 @@ Texture format that uses `BPTC ` **FORMAT_DXT5_RA_AS_RG** = ``34`` - +The `S3TC `__ texture format also known as Block Compression 3 or BC3, which compresses RA data and interprets it as two channels (red and green). See also :ref:`FORMAT_DXT5`. .. _class_Image_constant_FORMAT_ASTC_4x4: @@ -603,7 +603,7 @@ On the other hand, if the image already has mipmaps, they will be used, and a ne :ref:`Interpolation` **INTERPOLATE_LANCZOS** = ``4`` -Performs Lanczos interpolation. This is the slowest image resizing mode, but it typically gives the best results, especially when downscalng images. +Performs Lanczos interpolation. This is the slowest image resizing mode, but it typically gives the best results, especially when downscaling images. .. rst-class:: classref-item-separator @@ -713,7 +713,7 @@ enum **UsedChannels**: :ref:`UsedChannels` **USED_CHANNELS_L** = ``0`` - +The image only uses one channel for luminance (grayscale). .. _class_Image_constant_USED_CHANNELS_LA: @@ -721,7 +721,7 @@ enum **UsedChannels**: :ref:`UsedChannels` **USED_CHANNELS_LA** = ``1`` - +The image uses two channels for luminance and alpha, respectively. .. _class_Image_constant_USED_CHANNELS_R: @@ -729,7 +729,7 @@ enum **UsedChannels**: :ref:`UsedChannels` **USED_CHANNELS_R** = ``2`` - +The image only uses the red channel. .. _class_Image_constant_USED_CHANNELS_RG: @@ -737,7 +737,7 @@ enum **UsedChannels**: :ref:`UsedChannels` **USED_CHANNELS_RG** = ``3`` - +The image uses two channels for red and green. .. _class_Image_constant_USED_CHANNELS_RGB: @@ -745,7 +745,7 @@ enum **UsedChannels**: :ref:`UsedChannels` **USED_CHANNELS_RGB** = ``4`` - +The image uses three channels for red, green, and blue. .. _class_Image_constant_USED_CHANNELS_RGBA: @@ -753,7 +753,7 @@ enum **UsedChannels**: :ref:`UsedChannels` **USED_CHANNELS_RGBA** = ``5`` - +The image uses four channels for red, green, blue, and alpha. .. rst-class:: classref-item-separator @@ -872,9 +872,7 @@ Method Descriptions void **adjust_bcs** **(** :ref:`float` brightness, :ref:`float` contrast, :ref:`float` saturation **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Adjusts this image's ``brightness``, ``contrast``, and ``saturation`` by the given values. Does not work if the image is compressed (see :ref:`is_compressed`). .. rst-class:: classref-item-separator @@ -1090,9 +1088,7 @@ Returns :ref:`ALPHA_BLEND` if the image has da :ref:`UsedChannels` **detect_used_channels** **(** :ref:`CompressSource` source=0 **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the color channels used by this image, as one of the :ref:`UsedChannels` constants. If the image is compressed, the original ``source`` must be specified. .. rst-class:: classref-item-separator diff --git a/classes/class_input.rst b/classes/class_input.rst index b36ec486987..62b77b82306 100644 --- a/classes/class_input.rst +++ b/classes/class_input.rst @@ -42,11 +42,15 @@ Properties .. table:: :widths: auto - +----------------------------------------+--------------------------------------------------------------------------+ - | :ref:`MouseMode` | :ref:`mouse_mode` | - +----------------------------------------+--------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`use_accumulated_input` | - +----------------------------------------+--------------------------------------------------------------------------+ + +----------------------------------------+--------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`emulate_mouse_from_touch` | + +----------------------------------------+--------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`emulate_touch_from_mouse` | + +----------------------------------------+--------------------------------------------------------------------------------+ + | :ref:`MouseMode` | :ref:`mouse_mode` | + +----------------------------------------+--------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`use_accumulated_input` | + +----------------------------------------+--------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -379,6 +383,40 @@ Help cursor. Usually a question mark. Property Descriptions --------------------- +.. _class_Input_property_emulate_mouse_from_touch: + +.. rst-class:: classref-property + +:ref:`bool` **emulate_mouse_from_touch** + +.. rst-class:: classref-property-setget + +- void **set_emulate_mouse_from_touch** **(** :ref:`bool` value **)** +- :ref:`bool` **is_emulating_mouse_from_touch** **(** **)** + +If ``true``, sends mouse input events when tapping or swiping on the touchscreen. See also :ref:`ProjectSettings.input_devices/pointing/emulate_mouse_from_touch`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Input_property_emulate_touch_from_mouse: + +.. rst-class:: classref-property + +:ref:`bool` **emulate_touch_from_mouse** + +.. rst-class:: classref-property-setget + +- void **set_emulate_touch_from_mouse** **(** :ref:`bool` value **)** +- :ref:`bool` **is_emulating_touch_from_mouse** **(** **)** + +If ``true``, sends touch input events when clicking or dragging the mouse. See also :ref:`ProjectSettings.input_devices/pointing/emulate_touch_from_mouse`. + +.. rst-class:: classref-item-separator + +---- + .. _class_Input_property_mouse_mode: .. rst-class:: classref-property diff --git a/classes/class_inputeventmidi.rst b/classes/class_inputeventmidi.rst index 901b5215869..445e790aa54 100644 --- a/classes/class_inputeventmidi.rst +++ b/classes/class_inputeventmidi.rst @@ -190,7 +190,7 @@ If the message is :ref:`@GlobalScope.MIDI_MESSAGE_CONTROL_CHANGE` value **)** - :ref:`int` **get_instrument** **(** **)** -The instrument of this input event. This value ranges from 0 to 127. Refer to the instrument list on the General MIDI wikipedia article to see a list of instruments, except that this value is 0-index, so subtract one from every number on that chart. A standard piano will have an instrument number of 0. +The instrument of this input event. This value ranges from 0 to 127. Refer to the instrument list for `General MIDI `__ to see a list of instruments, except that this value is 0-index, so subtract one from every number on that chart. A standard piano will have an instrument number of 0. .. rst-class:: classref-item-separator diff --git a/classes/class_label.rst b/classes/class_label.rst index a2fc0ea1187..c1fc10a8678 100644 --- a/classes/class_label.rst +++ b/classes/class_label.rst @@ -41,6 +41,8 @@ Properties +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`clip_text` | ``false`` | +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`ellipsis_char` | ``"…"`` | + +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+ | :ref:`HorizontalAlignment` | :ref:`horizontal_alignment` | ``0`` | +-----------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------+ | |bitfield|\<:ref:`JustificationFlag`\> | :ref:`justification_flags` | ``163`` | @@ -88,15 +90,17 @@ Methods .. table:: :widths: auto - +-----------------------+--------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_line_count` **(** **)** |const| | - +-----------------------+--------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_line_height` **(** :ref:`int` line=-1 **)** |const| | - +-----------------------+--------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_total_character_count` **(** **)** |const| | - +-----------------------+--------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_visible_line_count` **(** **)** |const| | - +-----------------------+--------------------------------------------------------------------------------------------------------------+ + +---------------------------+--------------------------------------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`get_character_bounds` **(** :ref:`int` pos **)** |const| | + +---------------------------+--------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_line_count` **(** **)** |const| | + +---------------------------+--------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_line_height` **(** :ref:`int` line=-1 **)** |const| | + +---------------------------+--------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_total_character_count` **(** **)** |const| | + +---------------------------+--------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_visible_line_count` **(** **)** |const| | + +---------------------------+--------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -173,6 +177,23 @@ If ``true``, the Label only shows the text that fits inside its bounding rectang ---- +.. _class_Label_property_ellipsis_char: + +.. rst-class:: classref-property + +:ref:`String` **ellipsis_char** = ``"…"`` + +.. rst-class:: classref-property-setget + +- void **set_ellipsis_char** **(** :ref:`String` value **)** +- :ref:`String` **get_ellipsis_char** **(** **)** + +Ellipsis character used for text clipping. + +.. rst-class:: classref-item-separator + +---- + .. _class_Label_property_horizontal_alignment: .. rst-class:: classref-property @@ -471,6 +492,18 @@ The fraction of characters to display, relative to the total number of character Method Descriptions ------------------- +.. _class_Label_method_get_character_bounds: + +.. rst-class:: classref-method + +:ref:`Rect2` **get_character_bounds** **(** :ref:`int` pos **)** |const| + +Returns the bounding rectangle of the character at position ``pos``. If the character is a non-visual character or ``pos`` is outside the valid range, an empty :ref:`Rect2` is returned. If the character is a part of a composite grapheme, the bounding rectangle of the whole grapheme is returned. + +.. rst-class:: classref-item-separator + +---- + .. _class_Label_method_get_line_count: .. rst-class:: classref-method @@ -586,6 +619,8 @@ Text outline size. \ **Note:** If using a font with :ref:`FontFile.multichannel_signed_distance_field` enabled, its :ref:`FontFile.msdf_pixel_range` must be set to at least *twice* the value of :ref:`outline_size` for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. +\ **Note:** Using a value that is larger than half the font size is not recommended, as the font outline may fail to be fully closed in this case. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_lightmapgi.rst b/classes/class_lightmapgi.rst index 9b9bf0166ad..3eaf7ed608c 100644 --- a/classes/class_lightmapgi.rst +++ b/classes/class_lightmapgi.rst @@ -77,6 +77,8 @@ Properties +---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+ | :ref:`BakeQuality` | :ref:`quality` | ``1`` | +---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+ + | :ref:`float` | :ref:`texel_scale` | ``1.0`` | + +---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+ | :ref:`bool` | :ref:`use_denoiser` | ``true`` | +---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+ | :ref:`bool` | :ref:`use_texture_for_bounces` | ``true`` | @@ -587,6 +589,23 @@ To further speed up bake times, decrease :ref:`bounces` **texel_scale** = ``1.0`` + +.. rst-class:: classref-property-setget + +- void **set_texel_scale** **(** :ref:`float` value **)** +- :ref:`float` **get_texel_scale** **(** **)** + +Scales the lightmap texel density of all meshes for the current bake. This is a multiplier that builds upon the existing lightmap texel size defined in each imported 3D scene, along with the per-mesh density multiplier (which is designed to be used when the same mesh is used at different scales). Lower values will result in faster bake times. + +.. rst-class:: classref-item-separator + +---- + .. _class_LightmapGI_property_use_denoiser: .. rst-class:: classref-property diff --git a/classes/class_multiplayerpeer.rst b/classes/class_multiplayerpeer.rst index a526e66186f..0dd972b71bf 100644 --- a/classes/class_multiplayerpeer.rst +++ b/classes/class_multiplayerpeer.rst @@ -344,7 +344,7 @@ Returns the channel over which the next available packet was received. See :ref: :ref:`TransferMode` **get_packet_mode** **(** **)** |const| -Returns the :ref:`TransferMode` the remote peer used to send the next available packet. See :ref:`PacketPeer.get_available_packet_count`. +Returns the transfer mode the remote peer used to send the next available packet. See :ref:`PacketPeer.get_available_packet_count`. .. rst-class:: classref-item-separator diff --git a/classes/class_multiplayerpeerextension.rst b/classes/class_multiplayerpeerextension.rst index 2cbbcade068..281547621fd 100644 --- a/classes/class_multiplayerpeerextension.rst +++ b/classes/class_multiplayerpeerextension.rst @@ -176,7 +176,7 @@ Called to get the channel over which the next available packet was received. See :ref:`TransferMode` **_get_packet_mode** **(** **)** |virtual| |const| -Called to get the :ref:`TransferMode` the remote peer used to send the next available packet. See :ref:`MultiplayerPeer.get_packet_mode`. +Called to get the transfer mode the remote peer used to send the next available packet. See :ref:`MultiplayerPeer.get_packet_mode`. .. rst-class:: classref-item-separator diff --git a/classes/class_navigationagent2d.rst b/classes/class_navigationagent2d.rst index c9dbd0af47a..8a3e1024762 100644 --- a/classes/class_navigationagent2d.rst +++ b/classes/class_navigationagent2d.rst @@ -153,7 +153,7 @@ Signals **link_reached** **(** :ref:`Dictionary` details **)** -Notifies when a navigation link has been reached. +Signals that the agent reached a navigation link. Emitted when the agent moves within :ref:`path_desired_distance` of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of :ref:`path_metadata_flags`: @@ -179,7 +179,9 @@ The details dictionary may contain the following keys depending on the value of **navigation_finished** **(** **)** -Emitted once per loaded path when the agent internal navigation path index reaches the last index of the loaded path array. The agent internal navigation path index can be received with :ref:`get_current_navigation_path_index`. +Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. + +This signal will be emitted just after :ref:`target_reached` when the target is reachable. .. rst-class:: classref-item-separator @@ -209,7 +211,11 @@ Emitted when the agent had to update the loaded path: **target_reached** **(** **)** -Emitted once per loaded path when the agent's global position is the first time within :ref:`target_desired_distance` to the :ref:`target_position`. +Signals that the agent reached the target, i.e. the agent moved within :ref:`target_desired_distance` of the :ref:`target_position`. This signal is emitted only once per loaded path. + +This signal will be emitted just before :ref:`navigation_finished` when the target is reachable. + +It may not always be possible to reach the target but it should always be possible to reach the final position. See :ref:`get_final_position`. .. rst-class:: classref-item-separator @@ -233,7 +239,7 @@ Notifies when the collision avoidance velocity is calculated. Emitted when :ref: **waypoint_reached** **(** :ref:`Dictionary` details **)** -Notifies when a waypoint along the path has been reached. +Signals that the agent reached a waypoint. Emitted when the agent moves within :ref:`path_desired_distance` of the next position of the path. The details dictionary may contain the following keys depending on the value of :ref:`path_metadata_flags`: @@ -486,7 +492,7 @@ The distance to search for other agents. - void **set_path_desired_distance** **(** :ref:`float` value **)** - :ref:`float` **get_path_desired_distance** **(** **)** -The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the next point on each physics frame update. +The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update. .. rst-class:: classref-item-separator @@ -590,7 +596,11 @@ Does not affect normal pathfinding. To change an actor's pathfinding radius bake - void **set_target_desired_distance** **(** :ref:`float` value **)** - :ref:`float` **get_target_desired_distance** **(** **)** -The distance threshold before the final target point is considered to be reached. This allows agents to not have to hit the point of the final target exactly, but only to reach its general area. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the final target point on each physics frame update. +The distance threshold before the target is considered to be reached. On reaching the target, :ref:`target_reached` is emitted and navigation ends (see :ref:`is_navigation_finished` and :ref:`navigation_finished`). + +You can make navigation end early by setting this property to a value greater than :ref:`path_desired_distance` (navigation will end before reaching the last waypoint). + +You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than :ref:`path_desired_distance` (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update. .. rst-class:: classref-item-separator @@ -807,9 +817,9 @@ Returns the :ref:`RID` of this agent on the :ref:`NavigationServer2D< :ref:`bool` **is_navigation_finished** **(** **)** -Returns ``true`` if the end of the currently loaded navigation path has been reached. +Returns ``true`` if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. -\ **Note:** While true prefer to stop calling update functions like :ref:`get_next_path_position`. This avoids jittering the standing agent due to calling repeated path updates. +\ **Note:** While ``true`` prefer to stop calling update functions like :ref:`get_next_path_position`. This avoids jittering the standing agent due to calling repeated path updates. .. rst-class:: classref-item-separator @@ -833,7 +843,7 @@ Returns ``true`` if :ref:`get_final_position` **is_target_reached** **(** **)** |const| -Returns true if :ref:`target_position` is reached. It may not always be possible to reach the target position. It should always be possible to reach the final position though. See :ref:`get_final_position`. +Returns ``true`` if the agent reached the target, i.e. the agent moved within :ref:`target_desired_distance` of the :ref:`target_position`. It may not always be possible to reach the target but it should always be possible to reach the final position. See :ref:`get_final_position`. .. rst-class:: classref-item-separator diff --git a/classes/class_navigationagent3d.rst b/classes/class_navigationagent3d.rst index abcba3bae7d..b15e59a97dc 100644 --- a/classes/class_navigationagent3d.rst +++ b/classes/class_navigationagent3d.rst @@ -159,7 +159,7 @@ Signals **link_reached** **(** :ref:`Dictionary` details **)** -Notifies when a navigation link has been reached. +Signals that the agent reached a navigation link. Emitted when the agent moves within :ref:`path_desired_distance` of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of :ref:`path_metadata_flags`: @@ -185,7 +185,9 @@ The details dictionary may contain the following keys depending on the value of **navigation_finished** **(** **)** -Emitted once per loaded path when the agent internal navigation path index reaches the last index of the loaded path array. The agent internal navigation path index can be received with :ref:`get_current_navigation_path_index`. +Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. + +This signal will be emitted just after :ref:`target_reached` when the target is reachable. .. rst-class:: classref-item-separator @@ -215,7 +217,11 @@ Emitted when the agent had to update the loaded path: **target_reached** **(** **)** -Emitted once per loaded path when the agent's global position is the first time within :ref:`target_desired_distance` to the :ref:`target_position`. +Signals that the agent reached the target, i.e. the agent moved within :ref:`target_desired_distance` of the :ref:`target_position`. This signal is emitted only once per loaded path. + +This signal will be emitted just before :ref:`navigation_finished` when the target is reachable. + +It may not always be possible to reach the target but it should always be possible to reach the final position. See :ref:`get_final_position`. .. rst-class:: classref-item-separator @@ -239,7 +245,7 @@ Notifies when the collision avoidance velocity is calculated. Emitted when :ref: **waypoint_reached** **(** :ref:`Dictionary` details **)** -Notifies when a waypoint along the path has been reached. +Signals that the agent reached a waypoint. Emitted when the agent moves within :ref:`path_desired_distance` of the next position of the path. The details dictionary may contain the following keys depending on the value of :ref:`path_metadata_flags`: @@ -509,7 +515,7 @@ The distance to search for other agents. - void **set_path_desired_distance** **(** :ref:`float` value **)** - :ref:`float` **get_path_desired_distance** **(** **)** -The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the next point on each physics frame update. +The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update. .. rst-class:: classref-item-separator @@ -630,7 +636,11 @@ Does not affect normal pathfinding. To change an actor's pathfinding radius bake - void **set_target_desired_distance** **(** :ref:`float` value **)** - :ref:`float` **get_target_desired_distance** **(** **)** -The distance threshold before the final target point is considered to be reached. This allows agents to not have to hit the point of the final target exactly, but only to reach its general area. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the final target point on each physics frame update. +The distance threshold before the target is considered to be reached. On reaching the target, :ref:`target_reached` is emitted and navigation ends (see :ref:`is_navigation_finished` and :ref:`navigation_finished`). + +You can make navigation end early by setting this property to a value greater than :ref:`path_desired_distance` (navigation will end before reaching the last waypoint). + +You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than :ref:`path_desired_distance` (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update. .. rst-class:: classref-item-separator @@ -866,9 +876,9 @@ Returns the :ref:`RID` of this agent on the :ref:`NavigationServer3D< :ref:`bool` **is_navigation_finished** **(** **)** -Returns ``true`` if the end of the currently loaded navigation path has been reached. +Returns ``true`` if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. -\ **Note:** While true prefer to stop calling update functions like :ref:`get_next_path_position`. This avoids jittering the standing agent due to calling repeated path updates. +\ **Note:** While ``true`` prefer to stop calling update functions like :ref:`get_next_path_position`. This avoids jittering the standing agent due to calling repeated path updates. .. rst-class:: classref-item-separator @@ -892,7 +902,7 @@ Returns ``true`` if :ref:`get_final_position` **is_target_reached** **(** **)** |const| -Returns true if :ref:`target_position` is reached. It may not always be possible to reach the target position. It should always be possible to reach the final position though. See :ref:`get_final_position`. +Returns ``true`` if the agent reached the target, i.e. the agent moved within :ref:`target_desired_distance` of the :ref:`target_position`. It may not always be possible to reach the target but it should always be possible to reach the final position. See :ref:`get_final_position`. .. rst-class:: classref-item-separator diff --git a/classes/class_navigationlink2d.rst b/classes/class_navigationlink2d.rst index d7da9c51b34..b1c02aa3997 100644 --- a/classes/class_navigationlink2d.rst +++ b/classes/class_navigationlink2d.rst @@ -67,6 +67,8 @@ Methods +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`get_navigation_layer_value` **(** :ref:`int` layer_number **)** |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid` **(** **)** |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_global_end_position` **(** :ref:`Vector2` position **)** | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_global_start_position` **(** :ref:`Vector2` position **)** | @@ -251,6 +253,18 @@ Returns whether or not the specified layer of the :ref:`navigation_layers` **get_rid** **(** **)** |const| + +Returns the :ref:`RID` of this link on the :ref:`NavigationServer2D`. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationLink2D_method_set_global_end_position: .. rst-class:: classref-method diff --git a/classes/class_navigationlink3d.rst b/classes/class_navigationlink3d.rst index 9ed2fb436cd..6b9e96b0e5e 100644 --- a/classes/class_navigationlink3d.rst +++ b/classes/class_navigationlink3d.rst @@ -67,6 +67,8 @@ Methods +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`get_navigation_layer_value` **(** :ref:`int` layer_number **)** |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid` **(** **)** |const| | + +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_global_end_position` **(** :ref:`Vector3` position **)** | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_global_start_position` **(** :ref:`Vector3` position **)** | @@ -251,6 +253,18 @@ Returns whether or not the specified layer of the :ref:`navigation_layers` **get_rid** **(** **)** |const| + +Returns the :ref:`RID` of this link on the :ref:`NavigationServer3D`. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationLink3D_method_set_global_end_position: .. rst-class:: classref-method diff --git a/classes/class_navigationregion2d.rst b/classes/class_navigationregion2d.rst index 23624ff31ce..860ed9d6adf 100644 --- a/classes/class_navigationregion2d.rst +++ b/classes/class_navigationregion2d.rst @@ -85,6 +85,8 @@ Methods +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`get_region_rid` **(** **)** |const| | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid` **(** **)** |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_avoidance_layer_value` **(** :ref:`int` layer_number, :ref:`bool` value **)** | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_navigation_layer_value` **(** :ref:`int` layer_number, :ref:`bool` value **)** | @@ -327,6 +329,20 @@ Returns the current navigation map :ref:`RID` used by this region. :ref:`RID` **get_region_rid** **(** **)** |const| +Returns the :ref:`RID` of this region on the :ref:`NavigationServer2D`. + +\ *Deprecated.* Use :ref:`get_rid` instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationRegion2D_method_get_rid: + +.. rst-class:: classref-method + +:ref:`RID` **get_rid** **(** **)** |const| + Returns the :ref:`RID` of this region on the :ref:`NavigationServer2D`. Combined with :ref:`NavigationServer2D.map_get_closest_point_owner` can be used to identify the **NavigationRegion2D** closest to a point on the merged navigation map. .. rst-class:: classref-item-separator diff --git a/classes/class_navigationregion3d.rst b/classes/class_navigationregion3d.rst index d600a0f937d..7133ffcbdde 100644 --- a/classes/class_navigationregion3d.rst +++ b/classes/class_navigationregion3d.rst @@ -79,6 +79,8 @@ Methods +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`get_region_rid` **(** **)** |const| | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid` **(** **)** |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_navigation_layer_value` **(** :ref:`int` layer_number, :ref:`bool` value **)** | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_navigation_map` **(** :ref:`RID` navigation_map **)** | @@ -271,6 +273,20 @@ Returns the current navigation map :ref:`RID` used by this region. :ref:`RID` **get_region_rid** **(** **)** |const| +Returns the :ref:`RID` of this region on the :ref:`NavigationServer3D`. + +\ *Deprecated.* Use :ref:`get_rid` instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationRegion3D_method_get_rid: + +.. rst-class:: classref-method + +:ref:`RID` **get_rid** **(** **)** |const| + Returns the :ref:`RID` of this region on the :ref:`NavigationServer3D`. Combined with :ref:`NavigationServer3D.map_get_closest_point_owner` can be used to identify the **NavigationRegion3D** closest to a point on the merged navigation map. .. rst-class:: classref-item-separator diff --git a/classes/class_navigationserver2d.rst b/classes/class_navigationserver2d.rst index 19efc01bb7a..1c4d067cb62 100644 --- a/classes/class_navigationserver2d.rst +++ b/classes/class_navigationserver2d.rst @@ -57,10 +57,34 @@ Methods +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_get_avoidance_enabled` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`agent_get_avoidance_layers` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`agent_get_avoidance_mask` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_avoidance_priority` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`agent_get_map` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`agent_get_max_neighbors` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_max_speed` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_neighbor_distance` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_get_paused` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`agent_get_position` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_radius` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_time_horizon_agents` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_time_horizon_obstacles` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`agent_get_velocity` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`agent_has_avoidance_callback` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_is_map_changed` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`agent_set_avoidance_callback` **(** :ref:`RID` agent, :ref:`Callable` callback **)** | @@ -165,6 +189,8 @@ Methods +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedVector2Array` | :ref:`map_get_path` **(** :ref:`RID` map, :ref:`Vector2` origin, :ref:`Vector2` destination, :ref:`bool` optimize, :ref:`int` navigation_layers=1 **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`map_get_random_point` **(** :ref:`RID` map, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID[]` | :ref:`map_get_regions` **(** :ref:`RID` map **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`map_get_use_edge_connections` **(** :ref:`RID` map **)** |const| | @@ -185,10 +211,20 @@ Methods +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`obstacle_get_avoidance_enabled` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`obstacle_get_avoidance_layers` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`obstacle_get_map` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`obstacle_get_paused` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`obstacle_get_position` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`obstacle_get_radius` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`obstacle_get_velocity` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`obstacle_get_vertices` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`obstacle_set_avoidance_enabled` **(** :ref:`RID` obstacle, :ref:`bool` enabled **)** | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`obstacle_set_avoidance_layers` **(** :ref:`RID` obstacle, :ref:`int` layers **)** | @@ -227,6 +263,10 @@ Methods +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`region_get_owner_id` **(** :ref:`RID` region **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`region_get_random_point` **(** :ref:`RID` region, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`region_get_transform` **(** :ref:`RID` region **)** |const| | + +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`region_get_travel_cost` **(** :ref:`RID` region **)** |const| | +-----------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`region_get_use_edge_connections` **(** :ref:`RID` region **)** |const| | @@ -316,6 +356,42 @@ Return ``true`` if the specified ``agent`` uses avoidance. ---- +.. _class_NavigationServer2D_method_agent_get_avoidance_layers: + +.. rst-class:: classref-method + +:ref:`int` **agent_get_avoidance_layers** **(** :ref:`RID` agent **)** |const| + +Returns the ``avoidance_layers`` bitmask of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_avoidance_mask: + +.. rst-class:: classref-method + +:ref:`int` **agent_get_avoidance_mask** **(** :ref:`RID` agent **)** |const| + +Returns the ``avoidance_mask`` bitmask of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_avoidance_priority: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_avoidance_priority** **(** :ref:`RID` agent **)** |const| + +Returns the ``avoidance_priority`` of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_agent_get_map: .. rst-class:: classref-method @@ -328,6 +404,42 @@ Returns the navigation map :ref:`RID` the requested ``agent`` is curr ---- +.. _class_NavigationServer2D_method_agent_get_max_neighbors: + +.. rst-class:: classref-method + +:ref:`int` **agent_get_max_neighbors** **(** :ref:`RID` agent **)** |const| + +Returns the maximum number of other agents the specified ``agent`` takes into account in the navigation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_max_speed: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_max_speed** **(** :ref:`RID` agent **)** |const| + +Returns the maximum speed of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_neighbor_distance: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_neighbor_distance** **(** :ref:`RID` agent **)** |const| + +Returns the maximum distance to other agents the specified ``agent`` takes into account in the navigation. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_agent_get_paused: .. rst-class:: classref-method @@ -340,6 +452,78 @@ Returns ``true`` if the specified ``agent`` is paused. ---- +.. _class_NavigationServer2D_method_agent_get_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **agent_get_position** **(** :ref:`RID` agent **)** |const| + +Returns the position of the specified ``agent`` in world space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_radius: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_radius** **(** :ref:`RID` agent **)** |const| + +Returns the radius of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_time_horizon_agents: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_time_horizon_agents** **(** :ref:`RID` agent **)** |const| + +Returns the minimal amount of time for which the specified ``agent``'s velocities that are computed by the simulation are safe with respect to other agents. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_time_horizon_obstacles: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_time_horizon_obstacles** **(** :ref:`RID` agent **)** |const| + +Returns the minimal amount of time for which the specified ``agent``'s velocities that are computed by the simulation are safe with respect to static avoidance obstacles. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_get_velocity: + +.. rst-class:: classref-method + +:ref:`Vector2` **agent_get_velocity** **(** :ref:`RID` agent **)** |const| + +Returns the velocity of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_agent_has_avoidance_callback: + +.. rst-class:: classref-method + +:ref:`bool` **agent_has_avoidance_callback** **(** :ref:`RID` agent **)** |const| + +Return ``true`` if the specified ``agent`` has an avoidance callback. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_agent_is_map_changed: .. rst-class:: classref-method @@ -974,6 +1158,22 @@ Returns the navigation path to reach the destination from the origin. ``navigati ---- +.. _class_NavigationServer2D_method_map_get_random_point: + +.. rst-class:: classref-method + +:ref:`Vector2` **map_get_random_point** **(** :ref:`RID` map, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| + +Returns a random position picked from all map region polygons with matching ``navigation_layers``. + +If ``uniformly`` is ``true``, all map regions, polygons, and faces are weighted by their surface area (slower). + +If ``uniformly`` is ``false``, just a random region and a random polygon are picked (faster). + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_map_get_regions: .. rst-class:: classref-method @@ -1094,6 +1294,18 @@ Returns ``true`` if the provided ``obstacle`` has avoidance enabled. ---- +.. _class_NavigationServer2D_method_obstacle_get_avoidance_layers: + +.. rst-class:: classref-method + +:ref:`int` **obstacle_get_avoidance_layers** **(** :ref:`RID` obstacle **)** |const| + +Returns the ``avoidance_layers`` bitmask of the specified ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_obstacle_get_map: .. rst-class:: classref-method @@ -1118,6 +1330,54 @@ Returns ``true`` if the specified ``obstacle`` is paused. ---- +.. _class_NavigationServer2D_method_obstacle_get_position: + +.. rst-class:: classref-method + +:ref:`Vector2` **obstacle_get_position** **(** :ref:`RID` obstacle **)** |const| + +Returns the position of the specified ``obstacle`` in world space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_obstacle_get_radius: + +.. rst-class:: classref-method + +:ref:`float` **obstacle_get_radius** **(** :ref:`RID` obstacle **)** |const| + +Returns the radius of the specified dynamic ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_obstacle_get_velocity: + +.. rst-class:: classref-method + +:ref:`Vector2` **obstacle_get_velocity** **(** :ref:`RID` obstacle **)** |const| + +Returns the velocity of the specified dynamic ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_obstacle_get_vertices: + +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **obstacle_get_vertices** **(** :ref:`RID` obstacle **)** |const| + +Returns the outline vertices for the specified ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_obstacle_set_avoidance_enabled: .. rst-class:: classref-method @@ -1350,6 +1610,34 @@ Returns the ``ObjectID`` of the object which manages this region. ---- +.. _class_NavigationServer2D_method_region_get_random_point: + +.. rst-class:: classref-method + +:ref:`Vector2` **region_get_random_point** **(** :ref:`RID` region, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| + +Returns a random position picked from all region polygons with matching ``navigation_layers``. + +If ``uniformly`` is ``true``, all region polygons and faces are weighted by their surface area (slower). + +If ``uniformly`` is ``false``, just a random polygon and face is picked (faster). + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer2D_method_region_get_transform: + +.. rst-class:: classref-method + +:ref:`Transform2D` **region_get_transform** **(** :ref:`RID` region **)** |const| + +Returns the global transformation of this ``region``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer2D_method_region_get_travel_cost: .. rst-class:: classref-method diff --git a/classes/class_navigationserver3d.rst b/classes/class_navigationserver3d.rst index 6f1338dff4f..aef0e400a3f 100644 --- a/classes/class_navigationserver3d.rst +++ b/classes/class_navigationserver3d.rst @@ -57,12 +57,38 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_get_avoidance_enabled` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`agent_get_avoidance_layers` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`agent_get_avoidance_mask` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_avoidance_priority` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_height` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`agent_get_map` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`agent_get_max_neighbors` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_max_speed` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_neighbor_distance` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_get_paused` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`agent_get_position` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_radius` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_time_horizon_agents` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`agent_get_time_horizon_obstacles` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_get_use_3d_avoidance` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`agent_get_velocity` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`agent_has_avoidance_callback` **(** :ref:`RID` agent **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`agent_is_map_changed` **(** :ref:`RID` agent **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`agent_set_avoidance_callback` **(** :ref:`RID` agent, :ref:`Callable` callback **)** | @@ -179,6 +205,8 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedVector3Array` | :ref:`map_get_path` **(** :ref:`RID` map, :ref:`Vector3` origin, :ref:`Vector3` destination, :ref:`bool` optimize, :ref:`int` navigation_layers=1 **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`map_get_random_point` **(** :ref:`RID` map, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID[]` | :ref:`map_get_regions` **(** :ref:`RID` map **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`map_get_up` **(** :ref:`RID` map **)** |const| | @@ -205,12 +233,24 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`obstacle_get_avoidance_enabled` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`obstacle_get_avoidance_layers` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`obstacle_get_height` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`obstacle_get_map` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`obstacle_get_paused` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`obstacle_get_position` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`obstacle_get_radius` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`obstacle_get_use_3d_avoidance` **(** :ref:`RID` obstacle **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`obstacle_get_velocity` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector3Array` | :ref:`obstacle_get_vertices` **(** :ref:`RID` obstacle **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`obstacle_set_avoidance_enabled` **(** :ref:`RID` obstacle, :ref:`bool` enabled **)** | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`obstacle_set_avoidance_layers` **(** :ref:`RID` obstacle, :ref:`int` layers **)** | @@ -255,6 +295,10 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`region_get_owner_id` **(** :ref:`RID` region **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector3` | :ref:`region_get_random_point` **(** :ref:`RID` region, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`region_get_transform` **(** :ref:`RID` region **)** |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`region_get_travel_cost` **(** :ref:`RID` region **)** |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`region_get_use_edge_connections` **(** :ref:`RID` region **)** |const| | @@ -445,6 +489,54 @@ Returns ``true`` if the provided ``agent`` has avoidance enabled. ---- +.. _class_NavigationServer3D_method_agent_get_avoidance_layers: + +.. rst-class:: classref-method + +:ref:`int` **agent_get_avoidance_layers** **(** :ref:`RID` agent **)** |const| + +Returns the ``avoidance_layers`` bitmask of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_avoidance_mask: + +.. rst-class:: classref-method + +:ref:`int` **agent_get_avoidance_mask** **(** :ref:`RID` agent **)** |const| + +Returns the ``avoidance_mask`` bitmask of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_avoidance_priority: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_avoidance_priority** **(** :ref:`RID` agent **)** |const| + +Returns the ``avoidance_priority`` of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_height: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_height** **(** :ref:`RID` agent **)** |const| + +Returns the ``height`` of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_agent_get_map: .. rst-class:: classref-method @@ -457,6 +549,42 @@ Returns the navigation map :ref:`RID` the requested ``agent`` is curr ---- +.. _class_NavigationServer3D_method_agent_get_max_neighbors: + +.. rst-class:: classref-method + +:ref:`int` **agent_get_max_neighbors** **(** :ref:`RID` agent **)** |const| + +Returns the maximum number of other agents the specified ``agent`` takes into account in the navigation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_max_speed: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_max_speed** **(** :ref:`RID` agent **)** |const| + +Returns the maximum speed of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_neighbor_distance: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_neighbor_distance** **(** :ref:`RID` agent **)** |const| + +Returns the maximum distance to other agents the specified ``agent`` takes into account in the navigation. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_agent_get_paused: .. rst-class:: classref-method @@ -469,6 +597,54 @@ Returns ``true`` if the specified ``agent`` is paused. ---- +.. _class_NavigationServer3D_method_agent_get_position: + +.. rst-class:: classref-method + +:ref:`Vector3` **agent_get_position** **(** :ref:`RID` agent **)** |const| + +Returns the position of the specified ``agent`` in world space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_radius: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_radius** **(** :ref:`RID` agent **)** |const| + +Returns the radius of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_time_horizon_agents: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_time_horizon_agents** **(** :ref:`RID` agent **)** |const| + +Returns the minimal amount of time for which the specified ``agent``'s velocities that are computed by the simulation are safe with respect to other agents. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_get_time_horizon_obstacles: + +.. rst-class:: classref-method + +:ref:`float` **agent_get_time_horizon_obstacles** **(** :ref:`RID` agent **)** |const| + +Returns the minimal amount of time for which the specified ``agent``'s velocities that are computed by the simulation are safe with respect to static avoidance obstacles. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_agent_get_use_3d_avoidance: .. rst-class:: classref-method @@ -481,6 +657,30 @@ Returns ``true`` if the provided ``agent`` uses avoidance in 3D space Vector3(x, ---- +.. _class_NavigationServer3D_method_agent_get_velocity: + +.. rst-class:: classref-method + +:ref:`Vector3` **agent_get_velocity** **(** :ref:`RID` agent **)** |const| + +Returns the velocity of the specified ``agent``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_agent_has_avoidance_callback: + +.. rst-class:: classref-method + +:ref:`bool` **agent_has_avoidance_callback** **(** :ref:`RID` agent **)** |const| + +Return ``true`` if the specified ``agent`` has an avoidance callback. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_agent_is_map_changed: .. rst-class:: classref-method @@ -685,7 +885,7 @@ void **agent_set_use_3d_avoidance** **(** :ref:`RID` agent, :ref:`boo Sets if the agent uses the 2D avoidance or the 3D avoidance while avoidance is enabled. -If ``true`` the agent calculates avoidance velocities in 3D for the xyz-axis, e.g. for games that take place in air, unterwater or space. The 3D using agent only avoids other 3D avoidance using agent's. The 3D using agent only reacts to radius based avoidance obstacles. The 3D using agent ignores any vertices based obstacles. The 3D using agent only avoids other 3D using agent's. +If ``true`` the agent calculates avoidance velocities in 3D for the xyz-axis, e.g. for games that take place in air, underwater or space. The 3D using agent only avoids other 3D avoidance using agent's. The 3D using agent only reacts to radius based avoidance obstacles. The 3D using agent ignores any vertices based obstacles. The 3D using agent only avoids other 3D using agent's. If ``false`` the agent calculates avoidance velocities in 2D along the xz-axis ignoring the y-axis. The 2D using agent only avoids other 2D avoidance using agent's. The 2D using agent reacts to radius avoidance obstacles. The 2D using agent reacts to vertices based avoidance obstacles. The 2D using agent only avoids other 2D using agent's. 2D using agents will ignore other 2D using agents or obstacles that are below their current position or above their current position including the agents height in 2D avoidance. @@ -1191,6 +1391,22 @@ Returns the navigation path to reach the destination from the origin. ``navigati ---- +.. _class_NavigationServer3D_method_map_get_random_point: + +.. rst-class:: classref-method + +:ref:`Vector3` **map_get_random_point** **(** :ref:`RID` map, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| + +Returns a random position picked from all map region polygons with matching ``navigation_layers``. + +If ``uniformly`` is ``true``, all map regions, polygons, and faces are weighted by their surface area (slower). + +If ``uniformly`` is ``false``, just a random region and a random polygon are picked (faster). + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_map_get_regions: .. rst-class:: classref-method @@ -1347,6 +1563,30 @@ Returns ``true`` if the provided ``obstacle`` has avoidance enabled. ---- +.. _class_NavigationServer3D_method_obstacle_get_avoidance_layers: + +.. rst-class:: classref-method + +:ref:`int` **obstacle_get_avoidance_layers** **(** :ref:`RID` obstacle **)** |const| + +Returns the ``avoidance_layers`` bitmask of the specified ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_obstacle_get_height: + +.. rst-class:: classref-method + +:ref:`float` **obstacle_get_height** **(** :ref:`RID` obstacle **)** |const| + +Returns the ``height`` of the specified ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_obstacle_get_map: .. rst-class:: classref-method @@ -1371,6 +1611,30 @@ Returns ``true`` if the specified ``obstacle`` is paused. ---- +.. _class_NavigationServer3D_method_obstacle_get_position: + +.. rst-class:: classref-method + +:ref:`Vector3` **obstacle_get_position** **(** :ref:`RID` obstacle **)** |const| + +Returns the position of the specified ``obstacle`` in world space. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_obstacle_get_radius: + +.. rst-class:: classref-method + +:ref:`float` **obstacle_get_radius** **(** :ref:`RID` obstacle **)** |const| + +Returns the radius of the specified dynamic ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_obstacle_get_use_3d_avoidance: .. rst-class:: classref-method @@ -1383,6 +1647,30 @@ Returns ``true`` if the provided ``obstacle`` uses avoidance in 3D space Vector3 ---- +.. _class_NavigationServer3D_method_obstacle_get_velocity: + +.. rst-class:: classref-method + +:ref:`Vector3` **obstacle_get_velocity** **(** :ref:`RID` obstacle **)** |const| + +Returns the velocity of the specified dynamic ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_obstacle_get_vertices: + +.. rst-class:: classref-method + +:ref:`PackedVector3Array` **obstacle_get_vertices** **(** :ref:`RID` obstacle **)** |const| + +Returns the outline vertices for the specified ``obstacle``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_obstacle_set_avoidance_enabled: .. rst-class:: classref-method @@ -1653,6 +1941,34 @@ Returns the ``ObjectID`` of the object which manages this region. ---- +.. _class_NavigationServer3D_method_region_get_random_point: + +.. rst-class:: classref-method + +:ref:`Vector3` **region_get_random_point** **(** :ref:`RID` region, :ref:`int` navigation_layers, :ref:`bool` uniformly **)** |const| + +Returns a random position picked from all region polygons with matching ``navigation_layers``. + +If ``uniformly`` is ``true``, all region polygons and faces are weighted by their surface area (slower). + +If ``uniformly`` is ``false``, just a random polygon and face is picked (faster). + +.. rst-class:: classref-item-separator + +---- + +.. _class_NavigationServer3D_method_region_get_transform: + +.. rst-class:: classref-method + +:ref:`Transform3D` **region_get_transform** **(** :ref:`RID` region **)** |const| + +Returns the global transformation of this ``region``. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationServer3D_method_region_get_travel_cost: .. rst-class:: classref-method diff --git a/classes/class_node.rst b/classes/class_node.rst index e95fc85feca..c6063292199 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -35,7 +35,7 @@ This means that when adding a node to the scene tree, the following order will b Nodes can also process input events. When present, the :ref:`_input` function will be called for each input that the program receives. In many cases, this can be overkill (unless used for simple projects), and the :ref:`_unhandled_input` function might be preferred; it is called when the input event was not handled by anyone else (typically, GUI :ref:`Control` nodes), ensuring that the node only receives the events that were meant for it. -To keep track of the scene hierarchy (especially when instancing scenes into other scenes), an "owner" can be set for the node with the :ref:`owner` property. This keeps track of who instantiated what. This is mostly useful when writing editors and tools, though. +To keep track of the scene hierarchy (especially when instantiating scenes into other scenes), an "owner" can be set for the node with the :ref:`owner` property. This keeps track of who instantiated what. This is mostly useful when writing editors and tools, though. Finally, when a node is freed with :ref:`Object.free` or :ref:`queue_free`, it will also free all its children. @@ -43,7 +43,7 @@ Finally, when a node is freed with :ref:`Object.free` \ **Networking with nodes:** After connecting to a server (or making one, see :ref:`ENetMultiplayerPeer`), it is possible to use the built-in RPC (remote procedure call) system to communicate over the network. By calling :ref:`rpc` with a method name, it will be called locally and in all connected peers (peers = clients and the server that accepts connections). To identify which node receives the RPC call, Godot will use its :ref:`NodePath` (make sure node names are the same on all peers). Also, take a look at the high-level networking tutorial and corresponding demos. -\ **Note:** The ``script`` property is part of the :ref:`Object` class, not **Node**. It isn't exposed like most properties but does have a setter and getter (``set_script()`` and ``get_script()``). +\ **Note:** The ``script`` property is part of the :ref:`Object` class, not **Node**. It isn't exposed like most properties but does have a setter and getter (see :ref:`Object.set_script` and :ref:`Object.get_script`). .. rst-class:: classref-introduction-group @@ -297,7 +297,7 @@ Signals **child_entered_tree** **(** :ref:`Node` node **)** -Emitted when a child node enters the scene tree, either because it entered on its own or because this node entered with it. +Emitted when the child ``node`` enters the :ref:`SceneTree`, usually because this node entered the tree (see :ref:`tree_entered`), or :ref:`add_child` has been called. This signal is emitted *after* the child node's own :ref:`NOTIFICATION_ENTER_TREE` and :ref:`tree_entered`. @@ -311,9 +311,9 @@ This signal is emitted *after* the child node's own :ref:`NOTIFICATION_ENTER_TRE **child_exiting_tree** **(** :ref:`Node` node **)** -Emitted when a child node is about to exit the scene tree, either because it is being removed or freed directly, or because this node is exiting the tree. +Emitted when the child ``node`` is about to exit the :ref:`SceneTree`, usually because this node is exiting the tree (see :ref:`tree_exiting`), or because the child ``node`` is being removed or freed. -When this signal is received, the child ``node`` is still in the tree and valid. This signal is emitted *after* the child node's own :ref:`tree_exiting` and :ref:`NOTIFICATION_EXIT_TREE`. +When this signal is received, the child ``node`` is still accessible inside the tree. This signal is emitted *after* the child node's own :ref:`tree_exiting` and :ref:`NOTIFICATION_EXIT_TREE`. .. rst-class:: classref-item-separator @@ -331,13 +331,25 @@ Emitted when the list of children is changed. This happens when child nodes are ---- +.. _class_Node_signal_editor_description_changed: + +.. rst-class:: classref-signal + +**editor_description_changed** **(** :ref:`Node` node **)** + +Emitted when the node's editor description field changed. + +.. rst-class:: classref-item-separator + +---- + .. _class_Node_signal_ready: .. rst-class:: classref-signal **ready** **(** **)** -Emitted when the node is ready. Comes after :ref:`_ready` callback and follows the same rules. +Emitted when the node is considered ready, after :ref:`_ready` is called. .. rst-class:: classref-item-separator @@ -349,7 +361,7 @@ Emitted when the node is ready. Comes after :ref:`_ready` is changed, if the node is inside the tree. .. rst-class:: classref-item-separator @@ -391,6 +403,8 @@ This signal is emitted *after* the related :ref:`NOTIFICATION_ENTER_TREE` notification. + .. rst-class:: classref-item-separator ---- @@ -401,9 +415,9 @@ Emitted after the node exits the tree and is no longer active. **tree_exiting** **(** **)** -Emitted when the node is still active but about to exit the tree. This is the right place for de-initialization (or a "destructor", if you will). +Emitted when the node is just about to exit the tree. The node is still valid. As such, this is the right place for de-initialization (or a "destructor", if you will). -This signal is emitted *before* the related :ref:`NOTIFICATION_EXIT_TREE` notification. +This signal is emitted *after* the node's :ref:`_exit_tree`, and *before* the related :ref:`NOTIFICATION_EXIT_TREE`. .. rst-class:: classref-section-separator @@ -426,7 +440,7 @@ enum **ProcessMode**: :ref:`ProcessMode` **PROCESS_MODE_INHERIT** = ``0`` -Inherits process mode from the node's parent. For the root node, it is equivalent to :ref:`PROCESS_MODE_PAUSABLE`. Default. +Inherits :ref:`process_mode` from the node's parent. For the root node, it is equivalent to :ref:`PROCESS_MODE_PAUSABLE`. This is the default for any newly created node. .. _class_Node_constant_PROCESS_MODE_PAUSABLE: @@ -434,7 +448,7 @@ Inherits process mode from the node's parent. For the root node, it is equivalen :ref:`ProcessMode` **PROCESS_MODE_PAUSABLE** = ``1`` -Stops processing when the :ref:`SceneTree` is paused (process when unpaused). This is the inverse of :ref:`PROCESS_MODE_WHEN_PAUSED`. +Stops processing when :ref:`SceneTree.paused` is ``true``. This is the inverse of :ref:`PROCESS_MODE_WHEN_PAUSED`. .. _class_Node_constant_PROCESS_MODE_WHEN_PAUSED: @@ -442,7 +456,7 @@ Stops processing when the :ref:`SceneTree` is paused (process w :ref:`ProcessMode` **PROCESS_MODE_WHEN_PAUSED** = ``2`` -Only process when the :ref:`SceneTree` is paused (don't process when unpaused). This is the inverse of :ref:`PROCESS_MODE_PAUSABLE`. +Process **only** when :ref:`SceneTree.paused` is ``true``. This is the inverse of :ref:`PROCESS_MODE_PAUSABLE`. .. _class_Node_constant_PROCESS_MODE_ALWAYS: @@ -450,7 +464,7 @@ Only process when the :ref:`SceneTree` is paused (don't process :ref:`ProcessMode` **PROCESS_MODE_ALWAYS** = ``3`` -Always process. Continue processing always, ignoring the :ref:`SceneTree`'s paused property. This is the inverse of :ref:`PROCESS_MODE_DISABLED`. +Always process. Keeps processing, ignoring :ref:`SceneTree.paused`. This is the inverse of :ref:`PROCESS_MODE_DISABLED`. .. _class_Node_constant_PROCESS_MODE_DISABLED: @@ -458,7 +472,7 @@ Always process. Continue processing always, ignoring the :ref:`SceneTree` **PROCESS_MODE_DISABLED** = ``4`` -Never process. Completely disables processing, ignoring the :ref:`SceneTree`'s paused property. This is the inverse of :ref:`PROCESS_MODE_ALWAYS`. +Never process. Completely disables processing, ignoring :ref:`SceneTree.paused`. This is the inverse of :ref:`PROCESS_MODE_ALWAYS`. .. rst-class:: classref-item-separator @@ -544,7 +558,7 @@ enum **DuplicateFlags**: :ref:`DuplicateFlags` **DUPLICATE_SIGNALS** = ``1`` -Duplicate the node's signals. +Duplicate the node's signal connections. .. _class_Node_constant_DUPLICATE_GROUPS: @@ -560,7 +574,7 @@ Duplicate the node's groups. :ref:`DuplicateFlags` **DUPLICATE_SCRIPTS** = ``4`` -Duplicate the node's scripts. +Duplicate the node's script (including the ancestor's script, if combined with :ref:`DUPLICATE_USE_INSTANTIATION`). .. _class_Node_constant_DUPLICATE_USE_INSTANTIATION: @@ -568,9 +582,7 @@ Duplicate the node's scripts. :ref:`DuplicateFlags` **DUPLICATE_USE_INSTANTIATION** = ``8`` -Duplicate using instancing. - -An instance stays linked to the original so when the original changes, the instance changes too. +Duplicate using :ref:`PackedScene.instantiate`. If the node comes from a scene saved on disk, re-uses :ref:`PackedScene.instantiate` as the base for the duplicated node and its children. .. rst-class:: classref-item-separator @@ -588,7 +600,7 @@ enum **InternalMode**: :ref:`InternalMode` **INTERNAL_MODE_DISABLED** = ``0`` -Node will not be internal. +The node will not be internal. .. _class_Node_constant_INTERNAL_MODE_FRONT: @@ -596,7 +608,7 @@ Node will not be internal. :ref:`InternalMode` **INTERNAL_MODE_FRONT** = ``1`` -Node will be placed at the front of parent's node list, before any non-internal sibling. +The node will be placed at the beginning of the parent's children list, before any non-internal sibling. .. _class_Node_constant_INTERNAL_MODE_BACK: @@ -604,7 +616,7 @@ Node will be placed at the front of parent's node list, before any non-internal :ref:`InternalMode` **INTERNAL_MODE_BACK** = ``2`` -Node will be placed at the back of parent's node list, after any non-internal sibling. +The node will be placed at the end of the parent's children list, after any non-internal sibling. .. rst-class:: classref-section-separator @@ -621,9 +633,9 @@ Constants **NOTIFICATION_ENTER_TREE** = ``10`` -Notification received when the node enters a :ref:`SceneTree`. +Notification received when the node enters a :ref:`SceneTree`. See :ref:`_enter_tree`. -This notification is emitted *before* the related :ref:`tree_entered`. +This notification is received *before* the related :ref:`tree_entered` signal. .. _class_Node_constant_NOTIFICATION_EXIT_TREE: @@ -631,9 +643,9 @@ This notification is emitted *before* the related :ref:`tree_entered`. +Notification received when the node is about to exit a :ref:`SceneTree`. See :ref:`_exit_tree`. -This notification is emitted *after* the related :ref:`tree_exiting`. +This notification is received *after* the related :ref:`tree_exiting` signal. .. _class_Node_constant_NOTIFICATION_MOVED_IN_PARENT: @@ -657,7 +669,7 @@ Notification received when the node is ready. See :ref:`_ready`. .. _class_Node_constant_NOTIFICATION_UNPAUSED: @@ -665,7 +677,7 @@ Notification received when the node is paused. **NOTIFICATION_UNPAUSED** = ``15`` -Notification received when the node is unpaused. +Notification received when the node is unpaused. See :ref:`process_mode`. .. _class_Node_constant_NOTIFICATION_PHYSICS_PROCESS: @@ -673,7 +685,7 @@ Notification received when the node is unpaused. **NOTIFICATION_PHYSICS_PROCESS** = ``16`` -Notification received every frame when the physics process flag is set (see :ref:`set_physics_process`). +Notification received from the tree every physics frame when :ref:`is_physics_processing` returns ``true``. See :ref:`_physics_process`. .. _class_Node_constant_NOTIFICATION_PROCESS: @@ -681,7 +693,7 @@ Notification received every frame when the physics process flag is set (see :ref **NOTIFICATION_PROCESS** = ``17`` -Notification received every frame when the process flag is set (see :ref:`set_process`). +Notification received from the tree every rendered frame when :ref:`is_processing` returns ``true``. See :ref:`_process`. .. _class_Node_constant_NOTIFICATION_PARENTED: @@ -689,9 +701,9 @@ Notification received every frame when the process flag is set (see :ref:`set_pr **NOTIFICATION_PARENTED** = ``18`` -Notification received when a node is set as a child of another node. +Notification received when the node is set as a child of another node (see :ref:`add_child` and :ref:`add_sibling`). -\ **Note:** This doesn't mean that a node entered the :ref:`SceneTree`. +\ **Note:** This does *not* mean that the node entered the :ref:`SceneTree`. .. _class_Node_constant_NOTIFICATION_UNPARENTED: @@ -699,7 +711,9 @@ Notification received when a node is set as a child of another node. **NOTIFICATION_UNPARENTED** = ``19`` -Notification received when a node is unparented (parent removed it from the list of children). +Notification received when the parent node calls :ref:`remove_child` on this node. + +\ **Note:** This does *not* mean that the node exited the :ref:`SceneTree`. .. _class_Node_constant_NOTIFICATION_SCENE_INSTANTIATED: @@ -707,7 +721,7 @@ Notification received when a node is unparented (parent removed it from the list **NOTIFICATION_SCENE_INSTANTIATED** = ``20`` -Notification received by scene owner when its scene is instantiated. +Notification received *only* by the newly instantiated scene root node, when :ref:`PackedScene.instantiate` is completed. .. _class_Node_constant_NOTIFICATION_DRAG_BEGIN: @@ -737,7 +751,7 @@ Use :ref:`Viewport.gui_is_drag_successful` or one of its ancestors' :ref:`name` is changed. This notification is *not* received when the node is removed from the :ref:`SceneTree`. .. _class_Node_constant_NOTIFICATION_CHILD_ORDER_CHANGED: @@ -753,7 +767,7 @@ Notification received when the list of children is changed. This happens when ch **NOTIFICATION_INTERNAL_PROCESS** = ``25`` -Notification received every frame when the internal process flag is set (see :ref:`set_process_internal`). +Notification received from the tree every rendered frame when :ref:`is_processing_internal` returns ``true``. .. _class_Node_constant_NOTIFICATION_INTERNAL_PHYSICS_PROCESS: @@ -761,7 +775,7 @@ Notification received every frame when the internal process flag is set (see :re **NOTIFICATION_INTERNAL_PHYSICS_PROCESS** = ``26`` -Notification received every frame when the internal physics process flag is set (see :ref:`set_physics_process_internal`). +Notification received from the tree every physics frame when :ref:`is_physics_processing_internal` returns ``true``. .. _class_Node_constant_NOTIFICATION_POST_ENTER_TREE: @@ -769,7 +783,7 @@ Notification received every frame when the internal physics process flag is set **NOTIFICATION_POST_ENTER_TREE** = ``27`` -Notification received when the node is ready, just before :ref:`NOTIFICATION_READY` is received. Unlike the latter, it's sent every time the node enters the tree, instead of only once. +Notification received when the node enters the tree, just before :ref:`NOTIFICATION_READY` may be received. Unlike the latter, it is sent every time the node enters tree, not just once. .. _class_Node_constant_NOTIFICATION_DISABLED: @@ -829,7 +843,7 @@ Implemented for embedded windows and on desktop and web platforms. **NOTIFICATION_WM_WINDOW_FOCUS_IN** = ``1004`` -Notification received when the node's parent :ref:`Window` is focused. This may be a change of focus between two windows of the same engine instance, or from the OS desktop or a third-party application to a window of the game (in which case :ref:`NOTIFICATION_APPLICATION_FOCUS_IN` is also emitted). +Notification received from the OS when the node's :ref:`Window` ancestor is focused. This may be a change of focus between two windows of the same engine instance, or from the OS desktop or a third-party application to a window of the game (in which case :ref:`NOTIFICATION_APPLICATION_FOCUS_IN` is also received). A :ref:`Window` node receives this notification when it is focused. @@ -839,7 +853,7 @@ A :ref:`Window` node receives this notification when it is focused **NOTIFICATION_WM_WINDOW_FOCUS_OUT** = ``1005`` -Notification received when the node's parent :ref:`Window` is defocused. This may be a change of focus between two windows of the same engine instance, or from a window of the game to the OS desktop or a third-party application (in which case :ref:`NOTIFICATION_APPLICATION_FOCUS_OUT` is also emitted). +Notification received from the OS when the node's :ref:`Window` ancestor is defocused. This may be a change of focus between two windows of the same engine instance, or from a window of the game to the OS desktop or a third-party application (in which case :ref:`NOTIFICATION_APPLICATION_FOCUS_OUT` is also received). A :ref:`Window` node receives this notification when it is defocused. @@ -861,7 +875,7 @@ Implemented on desktop platforms. Notification received from the OS when a go back request is sent (e.g. pressing the "Back" button on Android). -Specific to the Android platform. +Implemented only on iOS. .. _class_Node_constant_NOTIFICATION_WM_SIZE_CHANGED: @@ -869,7 +883,9 @@ Specific to the Android platform. **NOTIFICATION_WM_SIZE_CHANGED** = ``1008`` -Notification received from the OS when the window is resized. +Notification received when the window is resized. + +\ **Note:** Only the resized :ref:`Window` node receives this notification, and it's not propagated to the child nodes. .. _class_Node_constant_NOTIFICATION_WM_DPI_CHANGE: @@ -877,7 +893,7 @@ Notification received from the OS when the window is resized. **NOTIFICATION_WM_DPI_CHANGE** = ``1009`` -Notification received from the OS when the screen's DPI has been changed. Only implemented on macOS. +Notification received from the OS when the screen's dots per inch (DPI) scale is changed. Only implemented on macOS. .. _class_Node_constant_NOTIFICATION_VP_MOUSE_ENTER: @@ -903,7 +919,7 @@ Notification received when the mouse cursor leaves the :ref:`Viewport` is changed. .. rst-class:: classref-section-separator @@ -1011,7 +1027,7 @@ Property Descriptions - void **set_editor_description** **(** :ref:`String` value **)** - :ref:`String` **get_editor_description** **(** **)** -Add a custom description to a node. It will be displayed in a tooltip when hovered in editor's scene tree. +An optional description to the node. It will be displayed as a tooltip when hovering over the node in the editor's Scene dock. .. rst-class:: classref-item-separator @@ -1046,9 +1062,9 @@ The :ref:`MultiplayerAPI` instance associated with this no - void **set_name** **(** :ref:`StringName` value **)** - :ref:`StringName` **get_name** **(** **)** -The name of the node. This name is unique among the siblings (other child nodes from the same parent). When set to an existing name, the node will be automatically renamed. +The name of the node. This name must be unique among the siblings (other child nodes from the same parent). When set to an existing sibling's name, the node is automatically renamed. -\ **Note:** Auto-generated names might include the ``@`` character, which is reserved for unique names when using :ref:`add_child`. When setting the name manually, any ``@`` will be removed. +\ **Note:** When changing the name, the following characters will be removed: (``.`` ``:`` ``@`` ``/`` ``"`` ``%``). In particular, the ``@`` character is reserved for auto-generated names. See also :ref:`String.validate_node_name`. .. rst-class:: classref-item-separator @@ -1065,9 +1081,9 @@ The name of the node. This name is unique among the siblings (other child nodes - void **set_owner** **(** :ref:`Node` value **)** - :ref:`Node` **get_owner** **(** **)** -The node owner. A node can have any ancestor node as owner (i.e. a parent, grandparent, etc. node ascending in the tree). This implies that :ref:`add_child` should be called before setting the owner, so that this relationship of parenting exists. When saving a node (using :ref:`PackedScene`), all the nodes it owns will be saved with it. This allows for the creation of complex scene trees, with instancing and subinstancing. +The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a :ref:`PackedScene`, all the nodes it owns are also saved with it. -\ **Note:** If you want a child to be persisted to a :ref:`PackedScene`, you must set :ref:`owner` in addition to calling :ref:`add_child`. This is typically relevant for :doc:`tool scripts <../tutorials/plugins/running_code_in_the_editor>` and :doc:`editor plugins <../tutorials/plugins/editor/index>`. If a new node is added to the tree without setting its owner as an ancestor in that tree, it will be visible in the 2D/3D view, but not in the scene tree (and not persisted when packing or saving). +\ **Note:** In the editor, nodes not owned by the scene root are usually not displayed in the Scene dock, and will **not** be saved. To prevent this, remember to set the owner after calling :ref:`add_child`. See also (see :ref:`unique_name_in_owner`) .. rst-class:: classref-item-separator @@ -1084,7 +1100,7 @@ The node owner. A node can have any ancestor node as owner (i.e. a parent, grand - void **set_process_mode** **(** :ref:`ProcessMode` value **)** - :ref:`ProcessMode` **get_process_mode** **(** **)** -Can be used to pause or unpause the node, or make the node paused based on the :ref:`SceneTree`, or make it inherit the process mode from its parent (default). +The node's processing behavior (see :ref:`ProcessMode`). To check if the node is able to process, with the current mode and :ref:`SceneTree.paused`, use :ref:`can_process`. .. rst-class:: classref-item-separator @@ -1118,7 +1134,7 @@ Similar to :ref:`process_priority` but for - void **set_process_priority** **(** :ref:`int` value **)** - :ref:`int` **get_process_priority** **(** **)** -The node's priority in the execution order of the enabled processing callbacks (i.e. :ref:`NOTIFICATION_PROCESS`, :ref:`NOTIFICATION_PHYSICS_PROCESS` and their internal counterparts). Nodes whose process priority value is *lower* will have their processing callbacks executed first. +The node's execution order of the process callbacks (:ref:`_process`, :ref:`_physics_process`, and internal processing). Nodes whose priority value is *lower* call their process callbacks first, regardless of tree order. .. rst-class:: classref-item-separator @@ -1192,7 +1208,7 @@ Set whether the current thread group will process messages (calls to :ref:`call_ - void **set_scene_file_path** **(** :ref:`String` value **)** - :ref:`String` **get_scene_file_path** **(** **)** -If a scene is instantiated from a file, its topmost node contains the absolute file path from which it was loaded in :ref:`scene_file_path` (e.g. ``res://levels/1.tscn``). Otherwise, :ref:`scene_file_path` is set to an empty string. +The original scene's file path, if the node has been instantiated from a :ref:`PackedScene` file. Only scene root nodes contains this. .. rst-class:: classref-item-separator @@ -1209,9 +1225,9 @@ If a scene is instantiated from a file, its topmost node contains the absolute f - void **set_unique_name_in_owner** **(** :ref:`bool` value **)** - :ref:`bool` **is_unique_name_in_owner** **(** **)** -Sets this node's name as a unique name in its :ref:`owner`. This allows the node to be accessed as ``%Name`` instead of the full path, from any node within that scene. +If ``true``, the node can be accessed from any node sharing the same :ref:`owner` or from the :ref:`owner` itself, with special ``%Name`` syntax in :ref:`get_node`. -If another node with the same owner already had that name declared as unique, that other node's name will no longer be set as having a unique name. +\ **Note:** If another node with the same :ref:`owner` shares the same :ref:`name` as this node, the other node will no longer be accessible as unique. .. rst-class:: classref-section-separator @@ -1228,7 +1244,7 @@ Method Descriptions void **_enter_tree** **(** **)** |virtual| -Called when the node enters the :ref:`SceneTree` (e.g. upon instancing, scene changing, or after calling :ref:`add_child` in a script). If the node has children, its :ref:`_enter_tree` callback will be called first, and then that of the children. +Called when the node enters the :ref:`SceneTree` (e.g. upon instantiating, scene changing, or after calling :ref:`add_child` in a script). If the node has children, its :ref:`_enter_tree` callback will be called first, and then that of the children. Corresponds to the :ref:`NOTIFICATION_ENTER_TREE` notification in :ref:`Object._notification`. @@ -1347,7 +1363,7 @@ Corresponds to the :ref:`NOTIFICATION_READY` may be used. See also :ref:`_enter_tree`. -\ **Note:** :ref:`_ready` may be called only once for each node. After removing a node from the scene tree and adding it again, :ref:`_ready` will not be called a second time. This can be bypassed by requesting another call with :ref:`request_ready`, which may be called anywhere before adding the node again. +\ **Note:** This method may be called only once for each node. After removing a node from the scene tree and adding it again, :ref:`_ready` will **not** be called a second time. This can be bypassed by requesting another call with :ref:`request_ready`, which may be called anywhere before adding the node again. .. rst-class:: classref-item-separator @@ -1425,9 +1441,9 @@ Adds a child ``node``. Nodes can have any number of children, but every child mu If ``force_readable_name`` is ``true``, improves the readability of the added ``node``. If not named, the ``node`` is renamed to its type, and if it shares :ref:`name` with a sibling, a number is suffixed more appropriately. This operation is very slow. As such, it is recommended leaving this to ``false``, which assigns a dummy name featuring ``@`` in both situations. -If ``internal`` is different than :ref:`INTERNAL_MODE_DISABLED`, the child will be added as internal node. Such nodes are ignored by methods like :ref:`get_children`, unless their parameter ``include_internal`` is ``true``. The intended usage is to hide the internal nodes from the user, so the user won't accidentally delete or modify them. Used by some GUI nodes, e.g. :ref:`ColorPicker`. See :ref:`InternalMode` for available modes. +If ``internal`` is different than :ref:`INTERNAL_MODE_DISABLED`, the child will be added as internal node. These nodes are ignored by methods like :ref:`get_children`, unless their parameter ``include_internal`` is ``true``. The intended usage is to hide the internal nodes from the user, so the user won't accidentally delete or modify them. Used by some GUI nodes, e.g. :ref:`ColorPicker`. See :ref:`InternalMode` for available modes. -\ **Note:** If the child node already has a parent, the function will fail. Use :ref:`remove_child` first to remove the node from its current parent. For example: +\ **Note:** If ``node`` already has a parent, this method will fail. Use :ref:`remove_child` first to remove ``node`` from its current parent. For example: .. tabs:: @@ -1464,13 +1480,13 @@ If you need the child node to be added below a specific node in the list of chil void **add_sibling** **(** :ref:`Node` sibling, :ref:`bool` force_readable_name=false **)** -Adds a ``sibling`` node to current's node parent, at the same level as that node, right below it. +Adds a ``sibling`` node to this node's parent, and moves the added sibling right below this node. If ``force_readable_name`` is ``true``, improves the readability of the added ``sibling``. If not named, the ``sibling`` is renamed to its type, and if it shares :ref:`name` with a sibling, a number is suffixed more appropriately. This operation is very slow. As such, it is recommended leaving this to ``false``, which assigns a dummy name featuring ``@`` in both situations. Use :ref:`add_child` instead of this method if you don't need the child node to be added below a specific node in the list of children. -\ **Note:** If this node is internal, the new sibling will be internal too (see ``internal`` parameter in :ref:`add_child`). +\ **Note:** If this node is internal, the added sibling will be internal too (see :ref:`add_child`'s ``internal`` parameter). .. rst-class:: classref-item-separator @@ -1482,11 +1498,13 @@ Use :ref:`add_child` instead of this method if you void **add_to_group** **(** :ref:`StringName` group, :ref:`bool` persistent=false **)** -Adds the node to a group. Groups are helpers to name and organize a subset of nodes, for example "enemies" or "collectables". A node can be in any number of groups. Nodes can be assigned a group at any time, but will not be added until they are inside the scene tree (see :ref:`is_inside_tree`). See notes in the description, and the group methods in :ref:`SceneTree`. +Adds the node to the ``group``. Groups can be helpful to organize a subset of nodes, for example ``"enemies"`` or ``"collectables"``. See notes in the description, and the group methods in :ref:`SceneTree`. + +If ``persistent`` is ``true``, the group will be stored when saved inside a :ref:`PackedScene`. All groups created and displayed in the Node dock are persistent. -The ``persistent`` option is used when packing node to :ref:`PackedScene` and saving to file. Non-persistent groups aren't stored. +\ **Note:** To improve performance, the order of group names is *not* guaranteed and may vary between project runs. Therefore, do not rely on the group order. -\ **Note:** For performance reasons, the order of node groups is *not* guaranteed. The order of node groups should not be relied upon as it can vary across project runs. +\ **Note:** :ref:`SceneTree`'s group methods will *not* work on this node if not inside the tree (see :ref:`is_inside_tree`). .. rst-class:: classref-item-separator @@ -1522,7 +1540,7 @@ This function ensures that the calling of this function will succeed, no matter :ref:`bool` **can_process** **(** **)** |const| -Returns ``true`` if the node can process while the scene tree is paused (see :ref:`process_mode`). Always returns ``true`` if the scene tree is not paused, and ``false`` if the node is not in the tree. +Returns ``true`` if the node can receive processing notifications and input callbacks (:ref:`NOTIFICATION_PROCESS`, :ref:`_input`, etc) from the :ref:`SceneTree` and :ref:`Viewport`. The value depends on both the current :ref:`process_mode` and :ref:`SceneTree.paused`. Returns ``false`` if the node is not inside the tree. .. rst-class:: classref-item-separator @@ -1534,7 +1552,9 @@ Returns ``true`` if the node can process while the scene tree is paused (see :re :ref:`Tween` **create_tween** **(** **)** -Creates a new :ref:`Tween` and binds it to this node. This is equivalent of doing: +Creates a new :ref:`Tween` and binds it to this node. Fails if the node is not inside the tree. + +This is the equivalent of doing: .. tabs:: @@ -1561,11 +1581,9 @@ The Tween will start automatically on the next process frame or physics frame (d :ref:`Node` **duplicate** **(** :ref:`int` flags=15 **)** |const| -Duplicates the node, returning a new node. +Duplicates the node, returning a new node with all of its properties, signals and groups copied from the original. The behavior can be tweaked through the ``flags`` (see :ref:`DuplicateFlags`). -You can fine-tune the behavior using the ``flags`` (see :ref:`DuplicateFlags`). - -\ **Note:** It will not work properly if the node contains a script with constructor arguments (i.e. needs to supply arguments to :ref:`Object._init` method). In that case, the node will be duplicated without a script. +\ **Note:** For nodes with a :ref:`Script` attached, if :ref:`Object._init` has been defined with required parameters, the duplicated node will not have a :ref:`Script`. .. rst-class:: classref-item-separator @@ -1577,17 +1595,13 @@ You can fine-tune the behavior using the ``flags`` (see :ref:`DuplicateFlags` **find_child** **(** :ref:`String` pattern, :ref:`bool` recursive=true, :ref:`bool` owned=true **)** |const| -Finds the first descendant of this node whose name matches ``pattern`` as in :ref:`String.match`. Internal children are also searched over (see ``internal`` parameter in :ref:`add_child`). - -\ ``pattern`` does not match against the full path, just against individual node names. It is case-sensitive, with ``"*"`` matching zero or more characters and ``"?"`` matching any single character except ``"."``). - -If ``recursive`` is ``true``, all child nodes are included, even if deeply nested. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. If ``recursive`` is ``false``, only this node's direct children are matched. +Finds the first descendant of this node whose :ref:`name` matches ``pattern``, returning ``null`` if no match is found. The matching is done against node names, *not* their paths, through :ref:`String.match`. As such, it is case-sensitive, ``"*"`` matches zero or more characters, and ``"?"`` matches any single character. -If ``owned`` is ``true``, this method only finds nodes who have an assigned :ref:`owner`. This is especially important for scenes instantiated through a script, because those scenes don't have an owner. +If ``recursive`` is ``false``, only this node's direct children are checked. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. Internal children are also included in the search (see ``internal`` parameter in :ref:`add_child`). -Returns ``null`` if no matching **Node** is found. +If ``owned`` is ``true``, only descendants with a valid :ref:`owner` node are checked. -\ **Note:** As this method walks through all the descendants of the node, it is the slowest way to get a reference to another node. Whenever possible, consider using :ref:`get_node` with unique names instead (see :ref:`unique_name_in_owner`), or caching the node references into variable. +\ **Note:** This method can be very slow. Consider storing a reference to the found node in a variable. Alternatively, use :ref:`get_node` with unique names (see :ref:`unique_name_in_owner`). \ **Note:** To find all descendant nodes matching a pattern or a class type, see :ref:`find_children`. @@ -1601,21 +1615,17 @@ Returns ``null`` if no matching **Node** is found. :ref:`Node[]` **find_children** **(** :ref:`String` pattern, :ref:`String` type="", :ref:`bool` recursive=true, :ref:`bool` owned=true **)** |const| -Finds descendants of this node whose name matches ``pattern`` as in :ref:`String.match`, and/or type matches ``type`` as in :ref:`Object.is_class`. Internal children are also searched over (see ``internal`` parameter in :ref:`add_child`). +Finds all descendants of this node whose names match ``pattern``, returning an empty :ref:`Array` if no match is found. The matching is done against node names, *not* their paths, through :ref:`String.match`. As such, it is case-sensitive, ``"*"`` matches zero or more characters, and ``"?"`` matches any single character. -\ ``pattern`` does not match against the full path, just against individual node names. It is case-sensitive, with ``"*"`` matching zero or more characters and ``"?"`` matching any single character except ``"."``). +If ``type`` is not empty, only ancestors inheriting from ``type`` are included (see :ref:`Object.is_class`). -\ ``type`` will check equality or inheritance, and is case-sensitive. ``"Object"`` will match a node whose type is ``"Node"`` but not the other way around. +If ``recursive`` is ``false``, only this node's direct children are checked. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. Internal children are also included in the search (see ``internal`` parameter in :ref:`add_child`). -If ``recursive`` is ``true``, all child nodes are included, even if deeply nested. Nodes are checked in tree order, so this node's first direct child is checked first, then its own direct children, etc., before moving to the second direct child, and so on. If ``recursive`` is ``false``, only this node's direct children are matched. +If ``owned`` is ``true``, only descendants with a valid :ref:`owner` node are checked. -If ``owned`` is ``true``, this method only finds nodes who have an assigned :ref:`owner`. This is especially important for scenes instantiated through a script, because those scenes don't have an owner. +\ **Note:** This method can be very slow. Consider storing references to the found nodes in a variable. -Returns an empty array if no matching nodes are found. - -\ **Note:** As this method walks through all the descendants of the node, it is the slowest way to get references to other nodes. Whenever possible, consider caching the node references into variables. - -\ **Note:** If you only want to find the first descendant node that matches a pattern, see :ref:`find_child`. +\ **Note:** To find a single descendant node matching a pattern, see :ref:`find_child`. .. rst-class:: classref-item-separator @@ -1627,11 +1637,9 @@ Returns an empty array if no matching nodes are found. :ref:`Node` **find_parent** **(** :ref:`String` pattern **)** |const| -Finds the first parent of the current node whose name matches ``pattern`` as in :ref:`String.match`. - -\ ``pattern`` does not match against the full path, just against individual node names. It is case-sensitive, with ``"*"`` matching zero or more characters and ``"?"`` matching any single character except ``"."``). +Finds the first ancestor of this node whose :ref:`name` matches ``pattern``, returning ``null`` if no match is found. The matching is done through :ref:`String.match`. As such, it is case-sensitive, ``"*"`` matches zero or more characters, and ``"?"`` matches any single character. See also :ref:`find_child` and :ref:`find_children`. -\ **Note:** As this method walks upwards in the scene tree, it can be slow in large, deeply nested scene trees. Whenever possible, consider using :ref:`get_node` with unique names instead (see :ref:`unique_name_in_owner`), or caching the node references into variable. +\ **Note:** As this method walks upwards in the scene tree, it can be slow in large, deeply nested nodes. Consider storing a reference to the found node in a variable. Alternatively, use :ref:`get_node` with unique names (see :ref:`unique_name_in_owner`). .. rst-class:: classref-item-separator @@ -1643,13 +1651,21 @@ Finds the first parent of the current node whose name matches ``pattern`` as in :ref:`Node` **get_child** **(** :ref:`int` idx, :ref:`bool` include_internal=false **)** |const| -Returns a child node by its index (see :ref:`get_child_count`). This method is often used for iterating all children of a node. +Fetches a child node by its index. Each child node has an index relative its siblings (see :ref:`get_index`). The first child is at index 0. Negative values can also be used to start from the end of the list. This method can be used in combination with :ref:`get_child_count` to iterate over this node's children. If no child exists at the given index, this method returns ``null`` and an error is generated. -Negative indices access the children from the last one. +If ``include_internal`` is ``false``, internal children are ignored (see :ref:`add_child`'s ``internal`` parameter). -If ``include_internal`` is ``false``, internal children are skipped (see ``internal`` parameter in :ref:`add_child`). +:: + + # Assuming the following are children of this node, in order: + # First, Middle, Last. + + var a = get_child(0).name # a is "First" + var b = get_child(1).name # b is "Middle" + var b = get_child(2).name # b is "Last" + var c = get_child(-1).name # c is "Last" -To access a child node via its name, use :ref:`get_node`. +\ **Note:** To fetch a node by :ref:`NodePath`, use :ref:`get_node`. .. rst-class:: classref-item-separator @@ -1661,9 +1677,9 @@ To access a child node via its name, use :ref:`get_node` **get_child_count** **(** :ref:`bool` include_internal=false **)** |const| -Returns the number of child nodes. +Returns the number of children of this node. -If ``include_internal`` is ``false``, internal children aren't counted (see ``internal`` parameter in :ref:`add_child`). +If ``include_internal`` is ``false``, internal children are not counted (see :ref:`add_child`'s ``internal`` parameter). .. rst-class:: classref-item-separator @@ -1675,9 +1691,9 @@ If ``include_internal`` is ``false``, internal children aren't counted (see ``in :ref:`Node[]` **get_children** **(** :ref:`bool` include_internal=false **)** |const| -Returns an array of references to node's children. +Returns all children of this node inside an :ref:`Array`. -If ``include_internal`` is ``false``, the returned array won't include internal children (see ``internal`` parameter in :ref:`add_child`). +If ``include_internal`` is ``false``, excludes internal children from the returned array (see :ref:`add_child`'s ``internal`` parameter). .. rst-class:: classref-item-separator @@ -1689,26 +1705,26 @@ If ``include_internal`` is ``false``, the returned array won't include internal :ref:`StringName[]` **get_groups** **(** **)** |const| -Returns an array listing the groups that the node is a member of. +Returns an :ref:`Array` of group names that the node has been added to. -\ **Note:** For performance reasons, the order of node groups is *not* guaranteed. The order of node groups should not be relied upon as it can vary across project runs. +\ **Note:** To improve performance, the order of group names is *not* guaranteed and may vary between project runs. Therefore, do not rely on the group order. -\ **Note:** The engine uses some group names internally (all starting with an underscore). To avoid conflicts with internal groups, do not add custom groups whose name starts with an underscore. To exclude internal groups while looping over :ref:`get_groups`, use the following snippet: +\ **Note:** This method may also return some group names starting with an underscore (``_``). These are internally used by the engine. To avoid conflicts, do not use custom groups starting with underscores. To exclude internal groups, see the following code snippet: .. tabs:: .. code-tab:: gdscript - # Stores the node's non-internal groups only (as an array of Strings). + # Stores the node's non-internal groups only (as an array of StringNames). var non_internal_groups = [] for group in get_groups(): - if not group.begins_with("_"): + if not str(group).begins_with("_"): non_internal_groups.push_back(group) .. code-tab:: csharp - // Stores the node's non-internal groups only (as a List of strings). + // Stores the node's non-internal groups only (as a List of StringNames). List nonInternalGroups = new List(); foreach (string group in GetGroups()) { @@ -1728,9 +1744,9 @@ Returns an array listing the groups that the node is a member of. :ref:`int` **get_index** **(** :ref:`bool` include_internal=false **)** |const| -Returns the node's order in the scene tree branch. For example, if called on the first child node the position is ``0``. +Returns this node's order among its siblings. The first node's index is ``0``. See also :ref:`get_child`. -If ``include_internal`` is ``false``, the index won't take internal children into account, i.e. first non-internal child will have index of 0 (see ``internal`` parameter in :ref:`add_child`). +If ``include_internal`` is ``false``, returns the index ignoring internal children. The first, non-internal child will have an index of ``0`` (see :ref:`add_child`'s ``internal`` parameter). .. rst-class:: classref-item-separator @@ -1766,24 +1782,26 @@ Returns the peer ID of the multiplayer authority for this node. See :ref:`set_mu :ref:`Node` **get_node** **(** :ref:`NodePath` path **)** |const| -Fetches a node. The :ref:`NodePath` can be either a relative path (from the current node) or an absolute path (in the scene tree) to a node. If the path does not exist, ``null`` is returned and an error is logged. Attempts to access methods on the return value will result in an "Attempt to call on a null instance." error. +Fetches a node. The :ref:`NodePath` can either be a relative path (from this node), or an absolute path (from the :ref:`SceneTree.root`) to a node. If ``path`` does not point to a valid node, generates an error and returns ``null``. Attempts to access methods on the return value will result in an *"Attempt to call on a null instance."* error. -\ **Note:** Fetching absolute paths only works when the node is inside the scene tree (see :ref:`is_inside_tree`). +\ **Note:** Fetching by absolute path only works when the node is inside the scene tree (see :ref:`is_inside_tree`). -\ **Example:** Assume your current node is Character and the following tree: +\ **Example:** Assume this method is called from the Character node, inside the following tree: :: - /root - /root/Character - /root/Character/Sword - /root/Character/Backpack/Dagger - /root/MyGame - /root/Swamp/Alligator - /root/Swamp/Mosquito - /root/Swamp/Goblin + ┖╴root + ┠╴Character (you are here!) + ┃ ┠╴Sword + ┃ ┖╴Backpack + ┃ ┖╴Dagger + ┠╴MyGame + ┖╴Swamp + ┠╴Alligator + ┠╴Mosquito + ┖╴Goblin -Possible paths are: +The following calls will return a valid node: .. tabs:: @@ -1814,26 +1832,52 @@ Possible paths are: :ref:`Array` **get_node_and_resource** **(** :ref:`NodePath` path **)** -Fetches a node and one of its resources as specified by the :ref:`NodePath`'s subname (e.g. ``Area2D/CollisionShape2D:shape``). If several nested resources are specified in the :ref:`NodePath`, the last one will be fetched. +Fetches a node and its most nested resource as specified by the :ref:`NodePath`'s subname. Returns an :ref:`Array` of size ``3`` where: -The return value is an array of size 3: the first index points to the **Node** (or ``null`` if not found), the second index points to the :ref:`Resource` (or ``null`` if not found), and the third index is the remaining :ref:`NodePath`, if any. +- Element ``0`` is the **Node**, or ``null`` if not found; -For example, assuming that ``Area2D/CollisionShape2D`` is a valid node and that its ``shape`` property has been assigned a :ref:`RectangleShape2D` resource, one could have this kind of output: +- Element ``1`` is the subname's last nested :ref:`Resource`, or ``null`` if not found; + +- Element ``2`` is the remaining :ref:`NodePath`, referring to an existing, non-:ref:`Resource` property (see :ref:`Object.get_indexed`). + +\ **Example:** Assume that the child's :ref:`Sprite2D.texture` has been assigned a :ref:`AtlasTexture`: .. tabs:: .. code-tab:: gdscript - print(get_node_and_resource("Area2D/CollisionShape2D")) # [[CollisionShape2D:1161], Null, ] - print(get_node_and_resource("Area2D/CollisionShape2D:shape")) # [[CollisionShape2D:1161], [RectangleShape2D:1156], ] - print(get_node_and_resource("Area2D/CollisionShape2D:shape:extents")) # [[CollisionShape2D:1161], [RectangleShape2D:1156], :extents] + var a = get_node_and_resource("Area2D/Sprite2D") + print(a[0].name) # Prints Sprite2D + print(a[1]) # Prints + print(a[2]) # Prints ^"" + + var b = get_node_and_resource("Area2D/Sprite2D:texture:atlas") + print(b[0].name) # Prints Sprite2D + print(b[1].get_class()) # Prints AtlasTexture + print(b[2]) # Prints ^"" + + var c = get_node_and_resource("Area2D/Sprite2D:texture:atlas:region") + print(c[0].name) # Prints Sprite2D + print(c[1].get_class()) # Prints AtlasTexture + print(c[2]) # Prints ^":region" .. code-tab:: csharp - GD.Print(GetNodeAndResource("Area2D/CollisionShape2D")); // [[CollisionShape2D:1161], Null, ] - GD.Print(GetNodeAndResource("Area2D/CollisionShape2D:shape")); // [[CollisionShape2D:1161], [RectangleShape2D:1156], ] - GD.Print(GetNodeAndResource("Area2D/CollisionShape2D:shape:extents")); // [[CollisionShape2D:1161], [RectangleShape2D:1156], :extents] + var a = GetNodeAndResource(NodePath("Area2D/Sprite2D")); + GD.Print(a[0].Name); // Prints Sprite2D + GD.Print(a[1]); // Prints + GD.Print(a[2]); // Prints ^" + + var b = GetNodeAndResource(NodePath("Area2D/Sprite2D:texture:atlas")); + GD.Print(b[0].name); // Prints Sprite2D + GD.Print(b[1].get_class()); // Prints AtlasTexture + GD.Print(b[2]); // Prints ^"" + + var c = GetNodeAndResource(NodePath("Area2D/Sprite2D:texture:atlas:region")); + GD.Print(c[0].name); // Prints Sprite2D + GD.Print(c[1].get_class()); // Prints AtlasTexture + GD.Print(c[2]); // Prints ^":region" @@ -1847,7 +1891,7 @@ For example, assuming that ``Area2D/CollisionShape2D`` is a valid node and that :ref:`Node` **get_node_or_null** **(** :ref:`NodePath` path **)** |const| -Similar to :ref:`get_node`, but does not log an error if ``path`` does not point to a valid **Node**. +Fetches a node by :ref:`NodePath`. Similar to :ref:`get_node`, but does not generate an error if ``path`` does not point to a valid node. .. rst-class:: classref-item-separator @@ -1859,7 +1903,7 @@ Similar to :ref:`get_node`, but does not log an erro :ref:`Node` **get_parent** **(** **)** |const| -Returns the parent node of the current node, or ``null`` if the node lacks a parent. +Returns this node's parent node, or ``null`` if the node doesn't have a parent. .. rst-class:: classref-item-separator @@ -1871,7 +1915,7 @@ Returns the parent node of the current node, or ``null`` if the node lacks a par :ref:`NodePath` **get_path** **(** **)** |const| -Returns the absolute path of the current node. This only works if the current node is inside the scene tree (see :ref:`is_inside_tree`). +Returns the node's absolute path, relative to the :ref:`SceneTree.root`. If the node is not inside the scene tree, this method fails and returns an empty :ref:`NodePath`. .. rst-class:: classref-item-separator @@ -1883,11 +1927,11 @@ Returns the absolute path of the current node. This only works if the current no :ref:`NodePath` **get_path_to** **(** :ref:`Node` node, :ref:`bool` use_unique_path=false **)** |const| -Returns the relative :ref:`NodePath` from this node to the specified ``node``. Both nodes must be in the same scene or the function will fail. +Returns the relative :ref:`NodePath` from this node to the specified ``node``. Both nodes must be in the same :ref:`SceneTree`, otherwise this method fails and returns an empty :ref:`NodePath`. -If ``use_unique_path`` is ``true``, returns the shortest path considering unique node. +If ``use_unique_path`` is ``true``, returns the shortest path accounting for this node's unique name (see :ref:`unique_name_in_owner`). -\ **Note:** If you get a relative path which starts from a unique node, the path may be longer than a normal relative path due to the addition of the unique node's name. +\ **Note:** If you get a relative path which starts from a unique node, the path may be longer than a normal relative path, due to the addition of the unique node's name. .. rst-class:: classref-item-separator @@ -1899,7 +1943,7 @@ If ``use_unique_path`` is ``true``, returns the shortest path considering unique :ref:`float` **get_physics_process_delta_time** **(** **)** |const| -Returns the time elapsed (in seconds) since the last physics-bound frame (see :ref:`_physics_process`). This is always a constant value in physics processing unless the frames per second is changed via :ref:`Engine.physics_ticks_per_second`. +Returns the time elapsed (in seconds) since the last physics callback. This value is identical to :ref:`_physics_process`'s ``delta`` parameter, and is often consistent at run-time, unless :ref:`Engine.physics_ticks_per_second` is changed. See also :ref:`NOTIFICATION_PHYSICS_PROCESS`. .. rst-class:: classref-item-separator @@ -1911,7 +1955,7 @@ Returns the time elapsed (in seconds) since the last physics-bound frame (see :r :ref:`float` **get_process_delta_time** **(** **)** |const| -Returns the time elapsed (in seconds) since the last process callback. This value may vary from frame to frame. +Returns the time elapsed (in seconds) since the last process callback. This value is identical to :ref:`_process`'s ``delta`` parameter, and may vary from frame to frame. See also :ref:`NOTIFICATION_PROCESS`. .. rst-class:: classref-item-separator @@ -1923,7 +1967,7 @@ Returns the time elapsed (in seconds) since the last process callback. This valu :ref:`bool` **get_scene_instance_load_placeholder** **(** **)** |const| -Returns ``true`` if this is an instance load placeholder. See :ref:`InstancePlaceholder`. +Returns ``true`` if this node is an instance load placeholder. See :ref:`InstancePlaceholder` and :ref:`set_scene_instance_load_placeholder`. .. rst-class:: classref-item-separator @@ -1935,7 +1979,7 @@ Returns ``true`` if this is an instance load placeholder. See :ref:`InstancePlac :ref:`SceneTree` **get_tree** **(** **)** |const| -Returns the :ref:`SceneTree` that contains this node. Returns ``null`` and prints an error if this node is not inside the scene tree. See also :ref:`is_inside_tree`. +Returns the :ref:`SceneTree` that contains this node. If this node is not inside the tree, generates an error and returns ``null``. See also :ref:`is_inside_tree`. .. rst-class:: classref-item-separator @@ -1993,7 +2037,7 @@ Similar to :ref:`get_tree_string`, this retur :ref:`Viewport` **get_viewport** **(** **)** |const| -Returns the node's :ref:`Viewport`. +Returns the node's closest :ref:`Viewport` ancestor, if the node is inside the tree. Otherwise, returns ``null``. .. rst-class:: classref-item-separator @@ -2017,7 +2061,7 @@ Returns the :ref:`Window` that contains this node. If the node is :ref:`bool` **has_node** **(** :ref:`NodePath` path **)** |const| -Returns ``true`` if the node that the :ref:`NodePath` points to exists. +Returns ``true`` if the ``path`` points to a valid node. See also :ref:`get_node`. .. rst-class:: classref-item-separator @@ -2029,7 +2073,7 @@ Returns ``true`` if the node that the :ref:`NodePath` points to :ref:`bool` **has_node_and_resource** **(** :ref:`NodePath` path **)** |const| -Returns ``true`` if the :ref:`NodePath` points to a valid node and its subname points to a valid resource, e.g. ``Area2D/CollisionShape2D:shape``. Properties with a non-:ref:`Resource` type (e.g. nodes or primitive math types) are not considered resources. +Returns ``true`` if ``path`` points to a valid node and its subnames point to a valid :ref:`Resource`, e.g. ``Area2D/CollisionShape2D:shape``. Properties that are not :ref:`Resource` types (such as nodes or other :ref:`Variant` types) are not considered. See also :ref:`get_node_and_resource`. .. rst-class:: classref-item-separator @@ -2041,7 +2085,7 @@ Returns ``true`` if the :ref:`NodePath` points to a valid node a :ref:`bool` **is_ancestor_of** **(** :ref:`Node` node **)** |const| -Returns ``true`` if the given node is a direct or indirect child of the current node. +Returns ``true`` if the given ``node`` is a direct or indirect child of this node. .. rst-class:: classref-item-separator @@ -2053,7 +2097,7 @@ Returns ``true`` if the given node is a direct or indirect child of the current :ref:`bool` **is_displayed_folded** **(** **)** |const| -Returns ``true`` if the node is folded (collapsed) in the Scene dock. This method is only intended for use with editor tooling. +Returns ``true`` if the node is folded (collapsed) in the Scene dock. This method is intended to be used in editor plugins and tools. See also :ref:`set_display_folded`. .. rst-class:: classref-item-separator @@ -2065,7 +2109,7 @@ Returns ``true`` if the node is folded (collapsed) in the Scene dock. This metho :ref:`bool` **is_editable_instance** **(** :ref:`Node` node **)** |const| -Returns ``true`` if ``node`` has editable children enabled relative to this node. This method is only intended for use with editor tooling. +Returns ``true`` if ``node`` has editable children enabled relative to this node. This method is intended to be used in editor plugins and tools. See also :ref:`set_editable_instance`. .. rst-class:: classref-item-separator @@ -2077,7 +2121,7 @@ Returns ``true`` if ``node`` has editable children enabled relative to this node :ref:`bool` **is_greater_than** **(** :ref:`Node` node **)** |const| -Returns ``true`` if the given node occurs later in the scene hierarchy than the current node. +Returns ``true`` if the given ``node`` occurs later in the scene hierarchy than this node. A node occurring later is usually processed last. .. rst-class:: classref-item-separator @@ -2089,7 +2133,7 @@ Returns ``true`` if the given node occurs later in the scene hierarchy than the :ref:`bool` **is_in_group** **(** :ref:`StringName` group **)** |const| -Returns ``true`` if this node is in the specified group. See notes in the description, and the group methods in :ref:`SceneTree`. +Returns ``true`` if this node has been added to the given ``group``. See :ref:`add_to_group` and :ref:`remove_from_group`. See also notes in the description, and the :ref:`SceneTree`'s group methods. .. rst-class:: classref-item-separator @@ -2101,7 +2145,7 @@ Returns ``true`` if this node is in the specified group. See notes in the descri :ref:`bool` **is_inside_tree** **(** **)** |const| -Returns ``true`` if this node is currently inside a :ref:`SceneTree`. +Returns ``true`` if this node is currently inside a :ref:`SceneTree`. See also :ref:`get_tree`. .. rst-class:: classref-item-separator @@ -2235,9 +2279,9 @@ Returns ``true`` if the node is processing unhandled key input (see :ref:`set_pr void **move_child** **(** :ref:`Node` child_node, :ref:`int` to_index **)** -Moves a child node to a different index (order) among the other children. Since calls, signals, etc. are performed by tree order, changing the order of children nodes may be useful. If ``to_index`` is negative, the index will be counted from the end. +Moves ``child_node`` to the given index. A node's index is the order among its siblings. If ``to_index`` is negative, the index is counted from the end of the list. See also :ref:`get_child` and :ref:`get_index`. -\ **Note:** Internal children can only be moved within their expected "internal range" (see ``internal`` parameter in :ref:`add_child`). +\ **Note:** The processing order of several engine callbacks (:ref:`_ready`, :ref:`_process`, etc.) and notifications sent through :ref:`propagate_notification` is affected by tree order. :ref:`CanvasItem` nodes are also rendered in tree order. See also :ref:`process_priority`. .. rst-class:: classref-item-separator @@ -2273,9 +2317,9 @@ Similar to :ref:`call_thread_safe`, but for void **print_orphan_nodes** **(** **)** |static| -Prints all orphan nodes (nodes outside the :ref:`SceneTree`). Used for debugging. +Prints all orphan nodes (nodes outside the :ref:`SceneTree`). Useful for debugging. -\ **Note:** :ref:`print_orphan_nodes` only works in debug builds. When called in a project exported in release mode, :ref:`print_orphan_nodes` will not print anything. +\ **Note:** This method only works in debug builds. Does nothing in a project exported in release mode. .. rst-class:: classref-item-separator @@ -2287,18 +2331,18 @@ Prints all orphan nodes (nodes outside the :ref:`SceneTree`). U void **print_tree** **(** **)** -Prints the tree to stdout. Used mainly for debugging purposes. This version displays the path relative to the current node, and is good for copy/pasting into the :ref:`get_node` function. +Prints the node and its children to the console, recursively. The node does not have to be inside the tree. This method outputs :ref:`NodePath`\ s relative to this node, and is good for copy/pasting into :ref:`get_node`. See also :ref:`print_tree_pretty`. \ **Example output:**\ :: - TheGame - TheGame/Menu - TheGame/Menu/Label - TheGame/Menu/Camera2D - TheGame/SplashScreen - TheGame/SplashScreen/Camera2D + . + Menu + Menu/Label + Menu/Camera2D + SplashScreen + SplashScreen/Camera2D .. rst-class:: classref-item-separator @@ -2310,7 +2354,7 @@ Prints the tree to stdout. Used mainly for debugging purposes. This version disp void **print_tree_pretty** **(** **)** -Similar to :ref:`print_tree`, this prints the tree to stdout. This version displays a more graphical representation similar to what is displayed in the Scene Dock. It is useful for inspecting larger trees. +Prints the node and its children to the console, recursively. The node does not have to be inside the tree. Similar to :ref:`print_tree`, but the graphical representation looks like what is displayed in the editor's Scene dock. It is useful for inspecting larger trees. \ **Example output:**\ @@ -2333,7 +2377,9 @@ Similar to :ref:`print_tree`, this prints the tree void **propagate_call** **(** :ref:`StringName` method, :ref:`Array` args=[], :ref:`bool` parent_first=false **)** -Calls the given method (if present) with the arguments given in ``args`` on this node and recursively on all its children. If the ``parent_first`` argument is ``true``, the method will be called on the current node first, then on all its children. If ``parent_first`` is ``false``, the children will be called first. +Calls the given ``method`` name, passing ``args`` as arguments, on this node and all of its children, recursively. + +If ``parent_first`` is ``true``, the method is called on this node first, then on all of its children. If ``false``, the children's methods are called first. .. rst-class:: classref-item-separator @@ -2345,7 +2391,7 @@ Calls the given method (if present) with the arguments given in ``args`` on this void **propagate_notification** **(** :ref:`int` what **)** -Notifies the current node and all its children recursively by calling :ref:`Object.notification` on all of them. +Calls :ref:`Object.notification` with ``what`` on this node and all of its children, recursively. .. rst-class:: classref-item-separator @@ -2357,11 +2403,11 @@ Notifies the current node and all its children recursively by calling :ref:`Obje void **queue_free** **(** **)** -Queues a node for deletion at the end of the current frame. When deleted, all of its child nodes will be deleted as well, and all references to the node and its children will become invalid, see :ref:`Object.free`. +Queues this node to be deleted at the end of the current frame. When deleted, all of its children are deleted as well, and all references to the node and its children become invalid. -It is safe to call :ref:`queue_free` multiple times per frame on a node, and to :ref:`Object.free` a node that is currently queued for deletion. Use :ref:`Object.is_queued_for_deletion` to check whether a node will be deleted at the end of the frame. +Unlike with :ref:`Object.free`, the node is not deleted instantly, and it can still be accessed before deletion. It is also safe to call :ref:`queue_free` multiple times. Use :ref:`Object.is_queued_for_deletion` to check if the node will be deleted at the end of the frame. -The node will only be freed after all other deferred calls are finished, so using :ref:`queue_free` is not always the same as calling :ref:`Object.free` through :ref:`Object.call_deferred`. +\ **Note:** The node will only be freed after all other deferred calls are finished. Using this method is not always the same as calling :ref:`Object.free` through :ref:`Object.call_deferred`. .. rst-class:: classref-item-separator @@ -2373,9 +2419,9 @@ The node will only be freed after all other deferred calls are finished, so usin void **remove_child** **(** :ref:`Node` node **)** -Removes a child node. The node is NOT deleted and must be deleted manually. +Removes a child ``node``. The ``node``, along with its children, are **not** deleted. To delete a node, see :ref:`queue_free`. -\ **Note:** This function may set the :ref:`owner` of the removed Node (or its descendants) to be ``null``, if that :ref:`owner` is no longer a parent or ancestor. +\ **Note:** When this node is inside the tree, this method sets the :ref:`owner` of the removed ``node`` (or its descendants) to ``null``, if their :ref:`owner` is no longer an ancestor (see :ref:`is_ancestor_of`). .. rst-class:: classref-item-separator @@ -2387,7 +2433,7 @@ Removes a child node. The node is NOT deleted and must be deleted manually. void **remove_from_group** **(** :ref:`StringName` group **)** -Removes a node from the ``group``. Does nothing if the node is not in the ``group``. See notes in the description, and the group methods in :ref:`SceneTree`. +Removes the node from the given ``group``. Does nothing if the node is not in the ``group``. See also notes in the description, and the :ref:`SceneTree`'s group methods. .. rst-class:: classref-item-separator @@ -2399,7 +2445,7 @@ Removes a node from the ``group``. Does nothing if the node is not in the ``grou void **reparent** **(** :ref:`Node` new_parent, :ref:`bool` keep_global_transform=true **)** -Changes the parent of this **Node** to the ``new_parent``. The node needs to already have a parent. +Changes the parent of this **Node** to the ``new_parent``. The node needs to already have a parent. The node's :ref:`owner` is preserved if its owner is still reachable from the new location (i.e., the node is still a descendant of the new parent after the operation). If ``keep_global_transform`` is ``true``, the node's global transform will be preserved if supported. :ref:`Node2D`, :ref:`Node3D` and :ref:`Control` support this argument (but :ref:`Control` keeps only position). @@ -2413,13 +2459,11 @@ If ``keep_global_transform`` is ``true``, the node's global transform will be pr void **replace_by** **(** :ref:`Node` node, :ref:`bool` keep_groups=false **)** -Replaces a node in a scene by the given one. Subscriptions that pass through this node will be lost. - -If ``keep_groups`` is ``true``, the ``node`` is added to the same groups that the replaced node is in. +Replaces this node by the given ``node``. All children of this node are moved to ``node``. -\ **Note:** The given node will become the new parent of any child nodes that the replaced node had. +If ``keep_groups`` is ``true``, the ``node`` is added to the same groups that the replaced node is in (see :ref:`add_to_group`). -\ **Note:** The replaced node is not automatically freed, so you either need to keep it in a variable for later use or free it using :ref:`Object.free`. +\ **Warning:** The replaced node is removed from the tree, but it is **not** deleted. To prevent memory leaks, store a reference to the node in a variable, or use :ref:`Object.free`. .. rst-class:: classref-item-separator @@ -2431,7 +2475,9 @@ If ``keep_groups`` is ``true``, the ``node`` is added to the same groups that th void **request_ready** **(** **)** -Requests that :ref:`_ready` be called again. Note that the method won't be called immediately, but is scheduled for when the node is added to the scene tree again. :ref:`_ready` is called only for the node which requested it, which means that you need to request ready for each child if you want them to call :ref:`_ready` too (in which case, :ref:`_ready` will be called in the same order as it would normally). +Requests :ref:`_ready` to be called again the next time the node enters the tree. Does **not** immediately call :ref:`_ready`. + +\ **Note:** This method only affects the current node. If the node's children also need to request ready, this method needs to be called for each one of them. When the node and its children enter the tree again, the order of :ref:`_ready` callbacks will be the same as normal. .. rst-class:: classref-item-separator @@ -2443,9 +2489,11 @@ Requests that :ref:`_ready` be called again. N :ref:`Error` **rpc** **(** :ref:`StringName` method, ... **)** |vararg| -Sends a remote procedure call request for the given ``method`` to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same :ref:`NodePath`, including the exact same node name. Behavior depends on the RPC configuration for the given method, see :ref:`rpc_config` and :ref:`@GDScript.@rpc`. Methods are not exposed to RPCs by default. Returns ``null``. +Sends a remote procedure call request for the given ``method`` to peers on the network (and locally), sending additional arguments to the method called by the RPC. The call request will only be received by nodes with the same :ref:`NodePath`, including the exact same :ref:`name`. Behavior depends on the RPC configuration for the given ``method`` (see :ref:`rpc_config` and :ref:`@GDScript.@rpc`). By default, methods are not exposed to RPCs. -\ **Note:** You can only safely use RPCs on clients after you received the ``connected_to_server`` signal from the :ref:`MultiplayerAPI`. You also need to keep track of the connection state, either by the :ref:`MultiplayerAPI` signals like ``server_disconnected`` or by checking ``get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED``. +May return :ref:`@GlobalScope.OK` if the call is successful, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if the arguments passed in the ``method`` do not match, :ref:`@GlobalScope.ERR_UNCONFIGURED` if the node's :ref:`multiplayer` cannot be fetched (such as when the node is not inside the tree), :ref:`@GlobalScope.ERR_CONNECTION_ERROR` if :ref:`multiplayer`'s connection is not available. + +\ **Note:** You can only safely use RPCs on clients after you received the :ref:`MultiplayerAPI.connected_to_server` signal from the :ref:`MultiplayerAPI`. You also need to keep track of the connection state, either by the :ref:`MultiplayerAPI` signals like :ref:`MultiplayerAPI.server_disconnected` or by checking (``get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED``). .. rst-class:: classref-item-separator @@ -2457,18 +2505,17 @@ Sends a remote procedure call request for the given ``method`` to peers on the n void **rpc_config** **(** :ref:`StringName` method, :ref:`Variant` config **)** -Changes the RPC mode for the given ``method`` with the given ``config`` which should be ``null`` (to disable) or a :ref:`Dictionary` in the form: +Changes the RPC configuration for the given ``method``. ``config`` should either be ``null`` to disable the feature (as by default), or a :ref:`Dictionary` containing the following entries: -:: +- ``rpc_mode``: see :ref:`RPCMode`; - { - rpc_mode = MultiplayerAPI.RPCMode, - transfer_mode = MultiplayerPeer.TransferMode, - call_local = false, - channel = 0, - } +- ``transfer_mode``: see :ref:`TransferMode`; + +- ``call_local``: if ``true``, the method will also be called locally; + +- ``channel``: an :ref:`int` representing the channel to send the RPC on. -See :ref:`RPCMode` and :ref:`TransferMode`. An alternative is annotating methods and properties with the corresponding :ref:`@GDScript.@rpc` annotation (``@rpc("any_peer")``, ``@rpc("authority")``). By default, methods are not exposed to networking (and RPCs). +\ **Note:** In GDScript, this method corresponds to the :ref:`@GDScript.@rpc` annotation, with various parameters passed (``@rpc(any)``, ``@rpc(authority)``...). See also the :doc:`high-level multiplayer <../tutorials/networking/high_level_multiplayer>` tutorial. .. rst-class:: classref-item-separator @@ -2480,7 +2527,9 @@ See :ref:`RPCMode` and :ref:`TransferMode` **rpc_id** **(** :ref:`int` peer_id, :ref:`StringName` method, ... **)** |vararg| -Sends a :ref:`rpc` to a specific peer identified by ``peer_id`` (see :ref:`MultiplayerPeer.set_target_peer`). Returns ``null``. +Sends a :ref:`rpc` to a specific peer identified by ``peer_id`` (see :ref:`MultiplayerPeer.set_target_peer`). + +May return :ref:`@GlobalScope.OK` if the call is successful, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if the arguments passed in the ``method`` do not match, :ref:`@GlobalScope.ERR_UNCONFIGURED` if the node's :ref:`multiplayer` cannot be fetched (such as when the node is not inside the tree), :ref:`@GlobalScope.ERR_CONNECTION_ERROR` if :ref:`multiplayer`'s connection is not available. .. rst-class:: classref-item-separator @@ -2504,7 +2553,7 @@ Similar to :ref:`call_deferred_thread_group` fold **)** -Sets the folded state of the node in the Scene dock. This method is only intended for use with editor tooling. +If set to ``true``, the node appears folded in the Scene dock. As a result, all of its children are hidden. This method is intended to be used in editor plugins and tools, but it also works in release builds. See also :ref:`is_displayed_folded`. .. rst-class:: classref-item-separator @@ -2516,7 +2565,7 @@ Sets the folded state of the node in the Scene dock. This method is only intende void **set_editable_instance** **(** :ref:`Node` node, :ref:`bool` is_editable **)** -Sets the editable children state of ``node`` relative to this node. This method is only intended for use with editor tooling. +Set to ``true`` to allow all nodes owned by ``node`` to be available, and editable, in the Scene dock, even if their :ref:`owner` is not the scene root. This method is intended to be used in editor plugins and tools, but it also works in release builds. See also :ref:`is_editable_instance`. .. rst-class:: classref-item-separator @@ -2528,9 +2577,11 @@ Sets the editable children state of ``node`` relative to this node. This method void **set_multiplayer_authority** **(** :ref:`int` id, :ref:`bool` recursive=true **)** -Sets the node's multiplayer authority to the peer with the given peer ID. The multiplayer authority is the peer that has authority over the node on the network. Useful in conjunction with :ref:`rpc_config` and the :ref:`MultiplayerAPI`. Defaults to peer ID 1 (the server). If ``recursive``, the given peer is recursively set as the authority for all children of this node. +Sets the node's multiplayer authority to the peer with the given peer ``id``. The multiplayer authority is the peer that has authority over the node on the network. Defaults to peer ID 1 (the server). Useful in conjunction with :ref:`rpc_config` and the :ref:`MultiplayerAPI`. + +If ``recursive`` is ``true``, the given peer is recursively set as the authority for all children of this node. -\ **Warning:** This does **not** automatically replicate the new authority to other peers. It is developer's responsibility to do so. You can propagate the information about the new authority using :ref:`MultiplayerSpawner.spawn_function`, an RPC, or using a :ref:`MultiplayerSynchronizer`. Also, the parent's authority does **not** propagate to newly added children. +\ **Warning:** This does **not** automatically replicate the new authority to other peers. It is the developer's responsibility to do so. You may replicate the new authority's information using :ref:`MultiplayerSpawner.spawn_function`, an RPC, or a :ref:`MultiplayerSynchronizer`. Furthermore, the parent's authority does **not** propagate to newly added children. .. rst-class:: classref-item-separator @@ -2542,7 +2593,7 @@ Sets the node's multiplayer authority to the peer with the given peer ID. The mu void **set_physics_process** **(** :ref:`bool` enable **)** -Enables or disables physics (i.e. fixed framerate) processing. When a node is being processed, it will receive a :ref:`NOTIFICATION_PHYSICS_PROCESS` at a fixed (usually 60 FPS, see :ref:`Engine.physics_ticks_per_second` to change) interval (and the :ref:`_physics_process` callback will be called if exists). Enabled automatically if :ref:`_physics_process` is overridden. Any calls to this before :ref:`_ready` will be ignored. +If set to ``true``, enables physics (fixed framerate) processing. When a node is being processed, it will receive a :ref:`NOTIFICATION_PHYSICS_PROCESS` at a fixed (usually 60 FPS, see :ref:`Engine.physics_ticks_per_second` to change) interval (and the :ref:`_physics_process` callback will be called if exists). Enabled automatically if :ref:`_physics_process` is overridden. .. rst-class:: classref-item-separator @@ -2554,9 +2605,9 @@ Enables or disables physics (i.e. fixed framerate) processing. When a node is be void **set_physics_process_internal** **(** :ref:`bool` enable **)** -Enables or disables internal physics for this node. Internal physics processing happens in isolation from the normal :ref:`_physics_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or physics processing is disabled for scripting (:ref:`set_physics_process`). Only useful for advanced uses to manipulate built-in nodes' behavior. +If set to ``true``, enables internal physics for this node. Internal physics processing happens in isolation from the normal :ref:`_physics_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or physics processing is disabled for scripting (:ref:`set_physics_process`). -\ **Warning:** Built-in Nodes rely on the internal processing for their own logic, so changing this value from your code may lead to unexpected behavior. Script access to this internal logic is provided for specific advanced uses, but is unsafe and not supported. +\ **Warning:** Built-in nodes rely on internal processing for their internal logic. Disabling it is unsafe and may lead to unexpected behavior. Use this method if you know what you are doing. .. rst-class:: classref-item-separator @@ -2568,7 +2619,7 @@ Enables or disables internal physics for this node. Internal physics processing void **set_process** **(** :ref:`bool` enable **)** -Enables or disables processing. When a node is being processed, it will receive a :ref:`NOTIFICATION_PROCESS` on every drawn frame (and the :ref:`_process` callback will be called if exists). Enabled automatically if :ref:`_process` is overridden. Any calls to this before :ref:`_ready` will be ignored. +If set to ``true``, enables processing. When a node is being processed, it will receive a :ref:`NOTIFICATION_PROCESS` on every drawn frame (and the :ref:`_process` callback will be called if exists). Enabled automatically if :ref:`_process` is overridden. .. rst-class:: classref-item-separator @@ -2580,7 +2631,7 @@ Enables or disables processing. When a node is being processed, it will receive void **set_process_input** **(** :ref:`bool` enable **)** -Enables or disables input processing. This is not required for GUI controls! Enabled automatically if :ref:`_input` is overridden. Any calls to this before :ref:`_ready` will be ignored. +If set to ``true``, enables input processing. This is not required for GUI controls! Enabled automatically if :ref:`_input` is overridden. .. rst-class:: classref-item-separator @@ -2592,9 +2643,9 @@ Enables or disables input processing. This is not required for GUI controls! Ena void **set_process_internal** **(** :ref:`bool` enable **)** -Enables or disabled internal processing for this node. Internal processing happens in isolation from the normal :ref:`_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or processing is disabled for scripting (:ref:`set_process`). Only useful for advanced uses to manipulate built-in nodes' behavior. +If set to ``true``, enables internal processing for this node. Internal processing happens in isolation from the normal :ref:`_process` calls and is used by some nodes internally to guarantee proper functioning even if the node is paused or processing is disabled for scripting (:ref:`set_process`). -\ **Warning:** Built-in Nodes rely on the internal processing for their own logic, so changing this value from your code may lead to unexpected behavior. Script access to this internal logic is provided for specific advanced uses, but is unsafe and not supported. +\ **Warning:** Built-in nodes rely on internal processing for their internal logic. Disabling it is unsafe and may lead to unexpected behavior. Use this method if you know what you are doing. .. rst-class:: classref-item-separator @@ -2606,7 +2657,7 @@ Enables or disabled internal processing for this node. Internal processing happe void **set_process_shortcut_input** **(** :ref:`bool` enable **)** -Enables shortcut processing. Enabled automatically if :ref:`_shortcut_input` is overridden. Any calls to this before :ref:`_ready` will be ignored. +If set to ``true``, enables shortcut processing for this node. Enabled automatically if :ref:`_shortcut_input` is overridden. .. rst-class:: classref-item-separator @@ -2618,7 +2669,7 @@ Enables shortcut processing. Enabled automatically if :ref:`_shortcut_input` enable **)** -Enables unhandled input processing. This is not required for GUI controls! It enables the node to receive all input that was not previously handled (usually by a :ref:`Control`). Enabled automatically if :ref:`_unhandled_input` is overridden. Any calls to this before :ref:`_ready` will be ignored. +If set to ``true``, enables unhandled input processing. This is not required for GUI controls! It enables the node to receive all input that was not previously handled (usually by a :ref:`Control`). Enabled automatically if :ref:`_unhandled_input` is overridden. .. rst-class:: classref-item-separator @@ -2630,7 +2681,7 @@ Enables unhandled input processing. This is not required for GUI controls! It en void **set_process_unhandled_key_input** **(** :ref:`bool` enable **)** -Enables unhandled key input processing. Enabled automatically if :ref:`_unhandled_key_input` is overridden. Any calls to this before :ref:`_ready` will be ignored. +If set to ``true``, enables unhandled key input processing. Enabled automatically if :ref:`_unhandled_key_input` is overridden. .. rst-class:: classref-item-separator @@ -2642,7 +2693,7 @@ Enables unhandled key input processing. Enabled automatically if :ref:`_unhandle void **set_scene_instance_load_placeholder** **(** :ref:`bool` load_placeholder **)** -Sets whether this is an instance load placeholder. See :ref:`InstancePlaceholder`. +If set to ``true``, the node becomes a :ref:`InstancePlaceholder` when packed and instantiated from a :ref:`PackedScene`. See also :ref:`get_scene_instance_load_placeholder`. .. rst-class:: classref-item-separator @@ -2666,9 +2717,7 @@ Similar to :ref:`call_thread_safe`, but for void **update_configuration_warnings** **(** **)** -Updates the warning displayed for this node in the Scene Dock. - -Use :ref:`_get_configuration_warnings` to setup the warning message to display. +Refreshes the warnings displayed for this node in the Scene dock. Use :ref:`_get_configuration_warnings` to customize the warning messages to display. .. |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_nodepath.rst b/classes/class_nodepath.rst index af615acf25e..c336e3a76b8 100644 --- a/classes/class_nodepath.rst +++ b/classes/class_nodepath.rst @@ -269,14 +269,14 @@ Gets the node name indicated by ``idx`` (0 to :ref:`get_name_countPropertyUsageFlags<() | PropertyUsageFlags.ReadOnly; + var usage = property["usage"].As() | PropertyUsageFlags.ReadOnly; property["usage"] = (int)usage; } } diff --git a/classes/class_openxrhand.rst b/classes/class_openxrhand.rst index 3c06b4f0911..8bffe399ae3 100644 --- a/classes/class_openxrhand.rst +++ b/classes/class_openxrhand.rst @@ -12,14 +12,18 @@ OpenXRHand **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Node supporting finger tracking in OpenXR. +Node supporting hand and finger tracking in OpenXR. .. rst-class:: classref-introduction-group Description ----------- -This node enables OpenXR's hand tracking functionality. The node should be a child node of an :ref:`XROrigin3D` node, tracking will update its position to where the player's actual hand is positioned. This node also updates the skeleton of a properly skinned hand model. The hand mesh should be a child node of this node. +This node enables OpenXR's hand tracking functionality. The node should be a child node of an :ref:`XROrigin3D` node, tracking will update its position to the player's tracked hand Palm joint location (the center of the middle finger's metacarpal bone). This node also updates the skeleton of a properly skinned hand or avatar model. + +If the skeleton is a hand (one of the hand bones is the root node of the skeleton), then the skeleton will be placed relative to the hand palm location and the hand mesh and skeleton should be children of the OpenXRHand node. + +If the hand bones are part of a full skeleton, then the root of the hand will keep its location with the assumption that IK is used to position the hand and arm. .. rst-class:: classref-reftable-group @@ -36,6 +40,8 @@ Properties +-------------------------------------------------+---------------------------------------------------------------+------------------+ | :ref:`MotionRange` | :ref:`motion_range` | ``0`` | +-------------------------------------------------+---------------------------------------------------------------+------------------+ + | :ref:`SkeletonRig` | :ref:`skeleton_rig` | ``0`` | + +-------------------------------------------------+---------------------------------------------------------------+------------------+ .. rst-class:: classref-section-separator @@ -110,6 +116,40 @@ When player grips, hand skeleton conforms to the controller the player is holdin Maximum supported motion ranges. +.. rst-class:: classref-item-separator + +---- + +.. _enum_OpenXRHand_SkeletonRig: + +.. rst-class:: classref-enumeration + +enum **SkeletonRig**: + +.. _class_OpenXRHand_constant_SKELETON_RIG_OPENXR: + +.. rst-class:: classref-enumeration-constant + +:ref:`SkeletonRig` **SKELETON_RIG_OPENXR** = ``0`` + +An OpenXR compliant skeleton. + +.. _class_OpenXRHand_constant_SKELETON_RIG_HUMANOID: + +.. rst-class:: classref-enumeration-constant + +:ref:`SkeletonRig` **SKELETON_RIG_HUMANOID** = ``1`` + +A :ref:`SkeletonProfileHumanoid` compliant skeleton. + +.. _class_OpenXRHand_constant_SKELETON_RIG_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`SkeletonRig` **SKELETON_RIG_MAX** = ``2`` + +Maximum supported hands. + .. rst-class:: classref-section-separator ---- @@ -166,6 +206,23 @@ Set a :ref:`Skeleton3D` node for which the pose positions will Set the motion range (if supported) limiting the hand motion. +.. rst-class:: classref-item-separator + +---- + +.. _class_OpenXRHand_property_skeleton_rig: + +.. rst-class:: classref-property + +:ref:`SkeletonRig` **skeleton_rig** = ``0`` + +.. rst-class:: classref-property-setget + +- void **set_skeleton_rig** **(** :ref:`SkeletonRig` value **)** +- :ref:`SkeletonRig` **get_skeleton_rig** **(** **)** + +Set the type of skeleton rig the :ref:`hand_skeleton` is compliant with. + .. |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_openxrinterface.rst b/classes/class_openxrinterface.rst index d9284235c41..4bce1b673d1 100644 --- a/classes/class_openxrinterface.rst +++ b/classes/class_openxrinterface.rst @@ -73,6 +73,8 @@ Methods +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Quaternion` | :ref:`get_hand_joint_rotation` **(** :ref:`Hand` hand, :ref:`HandJoints` joint **)** |const| | +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`HandTrackedSource` | :ref:`get_hand_tracking_source` **(** :ref:`Hand` hand **)** |const| | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`HandMotionRange` | :ref:`get_motion_range` **(** :ref:`Hand` hand **)** |const| | +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_action_set_active` **(** :ref:`String` name **)** |const| | @@ -208,7 +210,7 @@ enum **HandMotionRange**: :ref:`HandMotionRange` **HAND_MOTION_RANGE_UNOBSTRUCTED** = ``0`` - +Full hand range, if user closes their hands, we make a full fist. .. _class_OpenXRInterface_constant_HAND_MOTION_RANGE_CONFORM_TO_CONTROLLER: @@ -216,7 +218,7 @@ enum **HandMotionRange**: :ref:`HandMotionRange` **HAND_MOTION_RANGE_CONFORM_TO_CONTROLLER** = ``1`` - +Conform to controller, if user closes their hands, the tracked data conforms to the shape of the controller. .. _class_OpenXRInterface_constant_HAND_MOTION_RANGE_MAX: @@ -224,7 +226,49 @@ enum **HandMotionRange**: :ref:`HandMotionRange` **HAND_MOTION_RANGE_MAX** = ``2`` +Maximum value for the motion range enum. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_OpenXRInterface_HandTrackedSource: + +.. rst-class:: classref-enumeration + +enum **HandTrackedSource**: + +.. _class_OpenXRInterface_constant_HAND_TRACKED_SOURCE_UNKNOWN: + +.. rst-class:: classref-enumeration-constant + +:ref:`HandTrackedSource` **HAND_TRACKED_SOURCE_UNKNOWN** = ``0`` + +The source of hand tracking data is unknown (the extension is likely unsupported). + +.. _class_OpenXRInterface_constant_HAND_TRACKED_SOURCE_UNOBSTRUCTED: + +.. rst-class:: classref-enumeration-constant + +:ref:`HandTrackedSource` **HAND_TRACKED_SOURCE_UNOBSTRUCTED** = ``1`` + +The source of hand tracking is unobstructed, this means that an accurate method of hand tracking is used, e.g. optical hand tracking, data gloves, etc. +.. _class_OpenXRInterface_constant_HAND_TRACKED_SOURCE_CONTROLLER: + +.. rst-class:: classref-enumeration-constant + +:ref:`HandTrackedSource` **HAND_TRACKED_SOURCE_CONTROLLER** = ``2`` + +The source of hand tracking is a controller, bone positions are inferred from controller inputs. + +.. _class_OpenXRInterface_constant_HAND_TRACKED_SOURCE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`HandTrackedSource` **HAND_TRACKED_SOURCE_MAX** = ``3`` + +Maximum value for the hand tracked source enum. .. rst-class:: classref-item-separator @@ -557,6 +601,8 @@ The display refresh rate for the current HMD. Only functional if this feature is Enable dynamic foveation adjustment, the interface must be initialized before this is accessible. If enabled foveation will automatically adjusted between low and :ref:`foveation_level`. +\ **Note:** Only works on compatibility renderer. + .. rst-class:: classref-item-separator ---- @@ -574,6 +620,8 @@ Enable dynamic foveation adjustment, the interface must be initialized before th Set foveation level from 0 (off) to 3 (high), the interface must be initialized before this is accessible. +\ **Note:** Only works on compatibility renderer. + .. rst-class:: classref-item-separator ---- @@ -696,6 +744,18 @@ If handtracking is enabled, returns the rotation of a joint (``joint``) of a han ---- +.. _class_OpenXRInterface_method_get_hand_tracking_source: + +.. rst-class:: classref-method + +:ref:`HandTrackedSource` **get_hand_tracking_source** **(** :ref:`Hand` hand **)** |const| + +If handtracking is enabled and hand tracking source is supported, gets the source of the hand tracking data for ``hand``. + +.. rst-class:: classref-item-separator + +---- + .. _class_OpenXRInterface_method_get_motion_range: .. rst-class:: classref-method diff --git a/classes/class_os.rst b/classes/class_os.rst index dd1a56e7484..eef3932818c 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -19,9 +19,9 @@ Provides access to common operating system functionalities. Description ----------- -This class wraps the most common functionalities for communicating with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. +The **OS** class wraps the most common functionalities for communicating with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. -\ **Note:** In Godot 4, **OS** functions related to window management were moved to the :ref:`DisplayServer` singleton. +\ **Note:** In Godot 4, **OS** functions related to window management, clipboard, and TTS were moved to the :ref:`DisplayServer` singleton (and the :ref:`Window` class). Functions related to time were removed and are only available in the :ref:`Time` class. .. rst-class:: classref-introduction-group @@ -215,6 +215,14 @@ The Vulkan rendering driver. It requires Vulkan 1.0 support and automatically us The OpenGL 3 rendering driver. It uses OpenGL 3.3 Core Profile on desktop platforms, OpenGL ES 3.0 on mobile devices, and WebGL 2.0 on Web. +.. _class_OS_constant_RENDERING_DRIVER_D3D12: + +.. rst-class:: classref-enumeration-constant + +:ref:`RenderingDriver` **RENDERING_DRIVER_D3D12** = ``2`` + +The Direct3D 12 rendering driver. + .. rst-class:: classref-item-separator ---- @@ -231,7 +239,7 @@ enum **SystemDir**: :ref:`SystemDir` **SYSTEM_DIR_DESKTOP** = ``0`` -Desktop directory path. +Refers to the Desktop directory path. .. _class_OS_constant_SYSTEM_DIR_DCIM: @@ -239,7 +247,7 @@ Desktop directory path. :ref:`SystemDir` **SYSTEM_DIR_DCIM** = ``1`` -DCIM (Digital Camera Images) directory path. +Refers to the DCIM (Digital Camera Images) directory path. .. _class_OS_constant_SYSTEM_DIR_DOCUMENTS: @@ -247,7 +255,7 @@ DCIM (Digital Camera Images) directory path. :ref:`SystemDir` **SYSTEM_DIR_DOCUMENTS** = ``2`` -Documents directory path. +Refers to the Documents directory path. .. _class_OS_constant_SYSTEM_DIR_DOWNLOADS: @@ -255,7 +263,7 @@ Documents directory path. :ref:`SystemDir` **SYSTEM_DIR_DOWNLOADS** = ``3`` -Downloads directory path. +Refers to the Downloads directory path. .. _class_OS_constant_SYSTEM_DIR_MOVIES: @@ -263,7 +271,7 @@ Downloads directory path. :ref:`SystemDir` **SYSTEM_DIR_MOVIES** = ``4`` -Movies directory path. +Refers to the Movies (or Videos) directory path. .. _class_OS_constant_SYSTEM_DIR_MUSIC: @@ -271,7 +279,7 @@ Movies directory path. :ref:`SystemDir` **SYSTEM_DIR_MUSIC** = ``5`` -Music directory path. +Refers to the Music directory path. .. _class_OS_constant_SYSTEM_DIR_PICTURES: @@ -279,7 +287,7 @@ Music directory path. :ref:`SystemDir` **SYSTEM_DIR_PICTURES** = ``6`` -Pictures directory path. +Refers to the Pictures directory path. .. _class_OS_constant_SYSTEM_DIR_RINGTONES: @@ -287,7 +295,7 @@ Pictures directory path. :ref:`SystemDir` **SYSTEM_DIR_RINGTONES** = ``7`` -Ringtones directory path. +Refers to the Ringtones directory path. .. rst-class:: classref-section-separator @@ -309,7 +317,9 @@ Property Descriptions - void **set_delta_smoothing** **(** :ref:`bool` value **)** - :ref:`bool` **is_delta_smoothing_enabled** **(** **)** -If ``true``, the engine filters the time delta measured between each frame, and attempts to compensate for random variation. This will only operate on systems where V-Sync is active. +If ``true``, the engine filters the time delta measured between each frame, and attempts to compensate for random variation. This only works on systems where V-Sync is active. + +\ **Note:** On start-up, this is the same as :ref:`ProjectSettings.application/run/delta_smoothing`. .. rst-class:: classref-item-separator @@ -328,6 +338,8 @@ If ``true``, the engine filters the time delta measured between each frame, and If ``true``, the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile. +\ **Note:** On start-up, this is the same as :ref:`ProjectSettings.application/run/low_processor_mode`. + .. rst-class:: classref-item-separator ---- @@ -343,7 +355,9 @@ If ``true``, the engine optimizes for low processor usage by only refreshing the - void **set_low_processor_usage_mode_sleep_usec** **(** :ref:`int` value **)** - :ref:`int` **get_low_processor_usage_mode_sleep_usec** **(** **)** -The amount of sleeping between frames when the low-processor usage mode is enabled (in microseconds). Higher values will result in lower CPU usage. +The amount of sleeping between frames when the low-processor usage mode is enabled, in microseconds. Higher values will result in lower CPU usage. See also :ref:`low_processor_usage_mode`. + +\ **Note:** On start-up, this is the same as :ref:`ProjectSettings.application/run/low_processor_mode_sleep_usec`. .. rst-class:: classref-section-separator @@ -360,7 +374,7 @@ Method Descriptions void **alert** **(** :ref:`String` text, :ref:`String` title="Alert!" **)** -Displays a modal dialog box using the host OS' facilities. Execution is blocked until the dialog is closed. +Displays a modal dialog box using the host platform's implementation. The engine execution is blocked until the dialog is closed. .. rst-class:: classref-item-separator @@ -372,7 +386,7 @@ Displays a modal dialog box using the host OS' facilities. Execution is blocked void **close_midi_inputs** **(** **)** -Shuts down system MIDI driver. +Shuts down the system MIDI driver. Godot will no longer receive :ref:`InputEventMIDI`. See also :ref:`open_midi_inputs` and :ref:`get_connected_midi_inputs`. \ **Note:** This method is implemented on Linux, macOS and Windows. @@ -386,7 +400,9 @@ Shuts down system MIDI driver. void **crash** **(** :ref:`String` message **)** -Crashes the engine (or the editor if called within a ``@tool`` script). This should *only* be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) :ref:`@GDScript.assert`, :ref:`@GlobalScope.push_error` or :ref:`alert`. See also :ref:`kill`. +Crashes the engine (or the editor if called within a ``@tool`` script). See also :ref:`kill`. + +\ **Note:** This method should *only* be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) :ref:`@GDScript.assert`, :ref:`@GlobalScope.push_error`, or :ref:`alert`. .. rst-class:: classref-item-separator @@ -400,9 +416,11 @@ Crashes the engine (or the editor if called within a ``@tool`` script). This sho Creates a new instance of Godot that runs independently. The ``arguments`` are used in the given order and separated by a space. -If the process creation succeeds, the method will return the new process ID, which you can use to monitor the process (and potentially terminate it with :ref:`kill`). If the process creation fails, the method will return ``-1``. +If the process is successfully created, the method will return the new process ID, which you can use to monitor the process (and potentially terminate it with :ref:`kill`). If the process cannot be created, the method will return ``-1``. -\ **Note:** This method is implemented on Android, iOS, Linux, macOS and Windows. +See :ref:`create_process` if you wish to run a different process. + +\ **Note:** This method is implemented on Android, Linux, macOS and Windows. .. rst-class:: classref-item-separator @@ -414,11 +432,11 @@ If the process creation succeeds, the method will return the new process ID, whi :ref:`int` **create_process** **(** :ref:`String` path, :ref:`PackedStringArray` arguments, :ref:`bool` open_console=false **)** -Creates a new process that runs independently of Godot. It will not terminate if Godot terminates. The path specified in ``path`` must exist and be executable file or macOS .app bundle. Platform path resolution will be used. The ``arguments`` are used in the given order and separated by a space. +Creates a new process that runs independently of Godot. It will not terminate when Godot terminates. The path specified in ``path`` must exist and be executable file or macOS .app bundle. Platform path resolution will be used. The ``arguments`` are used in the given order and separated by a space. -On Windows, if ``open_console`` is ``true`` and the process is a console app, a new terminal window will be opened. This is ignored on other platforms. +On Windows, if ``open_console`` is ``true`` and the process is a console app, a new terminal window will be opened. -If the process creation succeeds, the method will return the new process ID, which you can use to monitor the process (and potentially terminate it with :ref:`kill`). If the process creation fails, the method will return ``-1``. +If the process is successfully created, this method returns its process ID, which you can use to monitor the process (and potentially terminate it with :ref:`kill`). Otherwise this method returns ``-1``. For example, running another instance of the project: @@ -451,9 +469,9 @@ See :ref:`execute` if you wish to run an external comma void **delay_msec** **(** :ref:`int` msec **)** |const| -Delays execution of the current thread by ``msec`` milliseconds. ``msec`` must be greater than or equal to ``0``. Otherwise, :ref:`delay_msec` will do nothing and will print an error message. +Delays execution of the current thread by ``msec`` milliseconds. ``msec`` must be greater than or equal to ``0``. Otherwise, :ref:`delay_msec` does nothing and prints an error message. -\ **Note:** :ref:`delay_msec` is a *blocking* way to delay code execution. To delay code execution in a non-blocking way, see :ref:`SceneTree.create_timer`. Awaiting with :ref:`SceneTree.create_timer` will delay the execution of code placed below the ``await`` without affecting the rest of the project (or editor, for :ref:`EditorPlugin`\ s and :ref:`EditorScript`\ s). +\ **Note:** :ref:`delay_msec` is a *blocking* way to delay code execution. To delay code execution in a non-blocking way, you may use :ref:`SceneTree.create_timer`. Awaiting with :ref:`SceneTreeTimer` delays the execution of code placed below the ``await`` without affecting the rest of the project (or editor, for :ref:`EditorPlugin`\ s and :ref:`EditorScript`\ s). \ **Note:** When :ref:`delay_msec` is called on the main thread, it will freeze the project and will prevent it from redrawing and registering input until the delay has passed. When using :ref:`delay_msec` as part of an :ref:`EditorPlugin` or :ref:`EditorScript`, it will freeze the editor but won't freeze the project if it is currently running (since the project is an independent child process). @@ -467,9 +485,9 @@ Delays execution of the current thread by ``msec`` milliseconds. ``msec`` must b void **delay_usec** **(** :ref:`int` usec **)** |const| -Delays execution of the current thread by ``usec`` microseconds. ``usec`` must be greater than or equal to ``0``. Otherwise, :ref:`delay_usec` will do nothing and will print an error message. +Delays execution of the current thread by ``usec`` microseconds. ``usec`` must be greater than or equal to ``0``. Otherwise, :ref:`delay_usec` does nothing and prints an error message. -\ **Note:** :ref:`delay_usec` is a *blocking* way to delay code execution. To delay code execution in a non-blocking way, see :ref:`SceneTree.create_timer`. Awaiting with :ref:`SceneTree.create_timer` will delay the execution of code placed below the ``await`` without affecting the rest of the project (or editor, for :ref:`EditorPlugin`\ s and :ref:`EditorScript`\ s). +\ **Note:** :ref:`delay_usec` is a *blocking* way to delay code execution. To delay code execution in a non-blocking way, you may use :ref:`SceneTree.create_timer`. Awaiting with a :ref:`SceneTreeTimer` delays the execution of code placed below the ``await`` without affecting the rest of the project (or editor, for :ref:`EditorPlugin`\ s and :ref:`EditorScript`\ s). \ **Note:** When :ref:`delay_usec` is called on the main thread, it will freeze the project and will prevent it from redrawing and registering input until the delay has passed. When using :ref:`delay_usec` as part of an :ref:`EditorPlugin` or :ref:`EditorScript`, it will freeze the editor but won't freeze the project if it is currently running (since the project is an independent child process). @@ -483,13 +501,15 @@ Delays execution of the current thread by ``usec`` microseconds. ``usec`` must b :ref:`int` **execute** **(** :ref:`String` path, :ref:`PackedStringArray` arguments, :ref:`Array` output=[], :ref:`bool` read_stderr=false, :ref:`bool` open_console=false **)** -Executes a command. The file specified in ``path`` must exist and be executable. Platform path resolution will be used. The ``arguments`` are used in the given order, separated by spaces, and wrapped in quotes. If an ``output`` :ref:`Array` is provided, the complete shell output of the process will be appended as a single :ref:`String` element in ``output``. If ``read_stderr`` is ``true``, the output to the standard error stream will be included too. +Executes the given process in a *blocking* way. The file specified in ``path`` must exist and be executable. The system path resolution will be used. The ``arguments`` are used in the given order, separated by spaces, and wrapped in quotes. + +If an ``output`` array is provided, the complete shell output of the process is appended to ``output`` as a single :ref:`String` element. If ``read_stderr`` is ``true``, the output to the standard error stream is also appended to the array. -On Windows, if ``open_console`` is ``true`` and the process is a console app, a new terminal window will be opened. This is ignored on other platforms. +On Windows, if ``open_console`` is ``true`` and the process is a console app, a new terminal window is opened. -If the command is successfully executed, the method will return the exit code of the command, or ``-1`` if it fails. +This method returns the exit code of the command, or ``-1`` if the process fails to execute. -\ **Note:** The Godot thread will pause its execution until the executed command terminates. Use :ref:`Thread` to create a separate thread that will not pause the Godot thread, or use :ref:`create_process` to create a completely independent process. +\ **Note:** The main thread will be blocked until the executed command terminates. Use :ref:`Thread` to create a separate thread that will not block the main thread, or use :ref:`create_process` to create a completely independent process. For example, to retrieve a list of the working directory's contents: @@ -545,7 +565,28 @@ If you wish to access a shell built-in or execute a composite command, a platfor :ref:`Key` **find_keycode_from_string** **(** :ref:`String` string **)** |const| -Returns the keycode of the given string (e.g. "Escape"). +Finds the keycode for the given string. The returned values are equivalent to the :ref:`Key` constants. + + +.. tabs:: + + .. code-tab:: gdscript + + print(OS.find_keycode_from_string("C")) # Prints 67 (KEY_C) + print(OS.find_keycode_from_string("Escape")) # Prints 4194305 (KEY_ESCAPE) + print(OS.find_keycode_from_string("Shift+Tab")) # Prints 37748738 (KEY_MASK_SHIFT | KEY_TAB) + print(OS.find_keycode_from_string("Unknown")) # Prints 0 (KEY_NONE) + + .. code-tab:: csharp + + GD.Print(OS.FindKeycodeFromString("C")); // Prints C (Key.C) + GD.Print(OS.FindKeycodeFromString("Escape")); // Prints Escape (Key.Escape) + GD.Print(OS.FindKeycodeFromString("Shift+Tab")); // Prints 37748738 (KeyModifierMask.MaskShift | Key.Tab) + GD.Print(OS.FindKeycodeFromString("Unknown")); // Prints None (Key.None) + + + +See also :ref:`get_keycode_string`. .. rst-class:: classref-item-separator @@ -557,7 +598,9 @@ Returns the keycode of the given string (e.g. "Escape"). :ref:`String` **get_cache_dir** **(** **)** |const| -Returns the *global* cache data directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the ``XDG_CACHE_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_config_dir` and :ref:`get_data_dir`. +Returns the *global* cache data directory according to the operating system's standards. + +On the Linux/BSD platform, this path can be overridden by setting the ``XDG_CACHE_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_config_dir` and :ref:`get_data_dir`. Not to be confused with :ref:`get_user_data_dir`, which returns the *project-specific* user data path. @@ -579,7 +622,7 @@ You can also incorporate environment variables using the :ref:`get_environment` to define command-line arguments to be passed by the editor when running the project. -Here's a minimal example on how to parse command-line arguments into a dictionary using the ``--key=value`` form for arguments: +Here's a minimal example on how to parse command-line arguments into a :ref:`Dictionary` using the ``--key=value`` form for arguments: .. tabs:: @@ -588,7 +631,7 @@ Here's a minimal example on how to parse command-line arguments into a dictionar var arguments = {} for argument in OS.get_cmdline_args(): - if argument.find("=") > -1: + if argument.contains("="): var key_value = argument.split("=") arguments[key_value[0].lstrip("--")] = key_value[1] else: @@ -601,7 +644,7 @@ Here's a minimal example on how to parse command-line arguments into a dictionar var arguments = new Godot.Collections.Dictionary(); foreach (var argument in OS.GetCmdlineArgs()) { - if (argument.Find("=") > -1) + if (argument.Contains('=')) { string[] keyValue = argument.Split("="); arguments[keyValue[0].LStrip("--")] = keyValue[1]; @@ -616,7 +659,7 @@ Here's a minimal example on how to parse command-line arguments into a dictionar -\ **Note:** Passing custom user arguments directly is not recommended, as the engine may discard or modify them. Instead, the best way is to use the standard UNIX double dash (``--``) and then pass custom arguments, which the engine itself will ignore. These can be read via :ref:`get_cmdline_user_args`. +\ **Note:** Passing custom user arguments directly is not recommended, as the engine may discard or modify them. Instead, pass the standard UNIX double dash (``--``) and then the custom arguments, which the engine will ignore by design. These can be read via :ref:`get_cmdline_user_args`. .. rst-class:: classref-item-separator @@ -628,15 +671,17 @@ Here's a minimal example on how to parse command-line arguments into a dictionar :ref:`PackedStringArray` **get_cmdline_user_args** **(** **)** -Similar to :ref:`get_cmdline_args`, but this returns the user arguments (any argument passed after the double dash ``--`` or double plus ``++`` argument). These are left untouched by Godot for the user. ``++`` can be used in situations where ``--`` is intercepted by another program (such as ``startx``). - -For example, in the command line below, ``--fullscreen`` will not be returned in :ref:`get_cmdline_user_args` and ``--level 1`` will only be returned in :ref:`get_cmdline_user_args`: +Returns the command-line user arguments passed to the engine. User arguments are ignored by the engine and reserved for the user. They are passed after the double dash ``--`` argument. ``++`` may be used when ``--`` is intercepted by another program (such as ``startx``). :: - godot --fullscreen -- --level 1 - # Or: - godot --fullscreen ++ --level 1 + # Godot has been executed with the following command: + # godot --fullscreen -- --level=2 --hardcore + + OS.get_cmdline_args() # Returns ["--fullscreen", "--level=2", "--hardcore"] + OS.get_cmdline_user_args() # Returns ["--level=2", "--hardcore"] + +To get all passed arguments, use :ref:`get_cmdline_args`. .. rst-class:: classref-item-separator @@ -648,7 +693,9 @@ For example, in the command line below, ``--fullscreen`` will not be returned in :ref:`String` **get_config_dir** **(** **)** |const| -Returns the *global* user configuration directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the ``XDG_CONFIG_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_data_dir`. +Returns the *global* user configuration directory according to the operating system's standards. + +On the Linux/BSD platform, this path can be overridden by setting the ``XDG_CONFIG_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_data_dir`. Not to be confused with :ref:`get_user_data_dir`, which returns the *project-specific* user data path. @@ -662,9 +709,7 @@ Not to be confused with :ref:`get_user_data_dir` **get_connected_midi_inputs** **(** **)** -Returns an array of MIDI device names. - -The returned array will be empty if the system MIDI driver has not previously been initialized with :ref:`open_midi_inputs`. +Returns an array of connected MIDI device names, if they exist. Returns an empty array if the system MIDI driver has not previously been initialized with :ref:`open_midi_inputs`. See also :ref:`close_midi_inputs`. \ **Note:** This method is implemented on Linux, macOS and Windows. @@ -678,7 +723,9 @@ The returned array will be empty if the system MIDI driver has not previously be :ref:`String` **get_data_dir** **(** **)** |const| -Returns the *global* user data directory according to the operating system's standards. On the Linux/BSD platform, this path can be overridden by setting the ``XDG_DATA_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_config_dir`. +Returns the *global* user data directory according to the operating system's standards. + +On the Linux/BSD platform, this path can be overridden by setting the ``XDG_DATA_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_config_dir`. Not to be confused with :ref:`get_user_data_dir`, which returns the *project-specific* user data path. @@ -692,13 +739,13 @@ Not to be confused with :ref:`get_user_data_dir` **get_distribution_name** **(** **)** |const| -Returns the name of the distribution for Linux and BSD platforms (e.g. Ubuntu, Manjaro, OpenBSD, etc.). +Returns the name of the distribution for Linux and BSD platforms (e.g. "Ubuntu", "Manjaro", "OpenBSD", etc.). -Returns the same value as :ref:`get_name` for stock Android ROMs, but attempts to return the custom ROM name for popular Android derivatives such as LineageOS. +Returns the same value as :ref:`get_name` for stock Android ROMs, but attempts to return the custom ROM name for popular Android derivatives such as "LineageOS". Returns the same value as :ref:`get_name` for other platforms. -\ **Note:** This method is not supported on the web platform. It returns an empty string. +\ **Note:** This method is not supported on the Web platform. It returns an empty string. .. rst-class:: classref-item-separator @@ -710,10 +757,12 @@ Returns the same value as :ref:`get_name` for other pl :ref:`String` **get_environment** **(** :ref:`String` variable **)** |const| -Returns the value of an environment variable. Returns an empty string if the environment variable doesn't exist. +Returns the value of the given environment variable, or an empty string if ``variable`` doesn't exist. \ **Note:** Double-check the casing of ``variable``. Environment variable names are case-sensitive on all platforms except Windows. +\ **Note:** On macOS, applications do not have access to shell environment variables. + .. rst-class:: classref-item-separator ---- @@ -724,7 +773,7 @@ Returns the value of an environment variable. Returns an empty string if the env :ref:`String` **get_executable_path** **(** **)** |const| -Returns the path to the current engine executable. +Returns the file path to the current engine executable. \ **Note:** On macOS, always use :ref:`create_instance` instead of relying on executable path. @@ -738,9 +787,9 @@ Returns the path to the current engine executable. :ref:`PackedStringArray` **get_granted_permissions** **(** **)** |const| -On Android devices: With this function, you can get the list of dangerous permissions that have been granted. +On Android devices: Returns the list of dangerous permissions that have been granted. -On macOS (sandboxed applications only): This function returns the list of user selected folders accessible to the application. Use native file dialog to request folder access permission. +On macOS: Returns the list of user selected folders accessible to the application (sandboxed applications only). Use the native file dialog to request folder access permission. .. rst-class:: classref-item-separator @@ -752,9 +801,26 @@ On macOS (sandboxed applications only): This function returns the list of user s :ref:`String` **get_keycode_string** **(** :ref:`Key` code **)** |const| -Returns the given keycode as a string (e.g. Return values: ``"Escape"``, ``"Shift+Escape"``). +Returns the given keycode as a :ref:`String`. + + +.. tabs:: + + .. code-tab:: gdscript + + print(OS.get_keycode_string(KEY_C)) # Prints "C" + print(OS.get_keycode_string(KEY_ESCAPE)) # Prints "Escape" + print(OS.get_keycode_string(KEY_MASK_SHIFT | KEY_TAB)) # Prints "Shift+Tab" + + .. code-tab:: csharp + + GD.Print(OS.GetKeycodeString(Key.C)); // Prints "C" + GD.Print(OS.GetKeycodeString(Key.Escape)); // Prints "Escape" + GD.Print(OS.GetKeycodeString((Key)KeyModifierMask.MaskShift | Key.Tab)); // Prints "Shift+Tab" + -See also :ref:`InputEventKey.keycode` and :ref:`InputEventKey.get_keycode_with_modifiers`. + +See also :ref:`find_keycode_from_string`, :ref:`InputEventKey.keycode`, and :ref:`InputEventKey.get_keycode_with_modifiers`. .. rst-class:: classref-item-separator @@ -766,17 +832,19 @@ See also :ref:`InputEventKey.keycode` and :ref:`String` **get_locale** **(** **)** |const| -Returns the host OS locale as a string of the form ``language_Script_COUNTRY_VARIANT@extra``. If you want only the language code and not the fully specified locale from the OS, you can use :ref:`get_locale_language`. +Returns the host OS locale as a :ref:`String` of the form ``language_Script_COUNTRY_VARIANT@extra``. Every substring after ``language`` is optional and may not exist. + +- ``language`` - 2 or 3-letter `language code `__, in lower case. -\ ``language`` - 2 or 3-letter `language code `__, in lower case. +- ``Script`` - 4-letter `script code `__, in title case. -\ ``Script`` - optional, 4-letter `script code `__, in title case. +- ``COUNTRY`` - 2 or 3-letter `country code `__, in upper case. -\ ``COUNTRY`` - optional, 2 or 3-letter `country code `__, in upper case. +- ``VARIANT`` - language variant, region and sort order. The variant can have any number of underscored keywords. -\ ``VARIANT`` - optional, language variant, region and sort order. Variant can have any number of underscored keywords. +- ``extra`` - semicolon separated list of additional key words. This may include currency, calendar, sort order and numbering system information. -\ ``extra`` - optional, semicolon separated list of additional key words. Currency, calendar, sort order and numbering system information. +If you want only the language code and not the fully specified locale from the OS, you can use :ref:`get_locale_language`. .. rst-class:: classref-item-separator @@ -816,15 +884,17 @@ Returns the ID of the main thread. See :ref:`get_thread_caller_id` **get_memory_info** **(** **)** |const| -Returns the :ref:`Dictionary` with the following keys: +Returns a :ref:`Dictionary` containing information about the current memory with the following entries: -\ ``"physical"`` - total amount of usable physical memory, in bytes or ``-1`` if unknown. This value can be slightly less than the actual physical memory amount, since it does not include memory reserved by kernel and devices. +- ``"physical"`` - total amount of usable physical memory in bytes. This value can be slightly less than the actual physical memory amount, since it does not include memory reserved by the kernel and devices. -\ ``"free"`` - amount of physical memory, that can be immediately allocated without disk access or other costly operation, in bytes or ``-1`` if unknown. The process might be able to allocate more physical memory, but such allocation will require moving inactive pages to disk and can take some time. +- ``"free"`` - amount of physical memory, that can be immediately allocated without disk access or other costly operations, in bytes. The process might be able to allocate more physical memory, but this action will require moving inactive pages to disk, which can be expensive. -\ ``"available"`` - amount of memory, that can be allocated without extending the swap file(s), in bytes or ``-1`` if unknown. This value include both physical memory and swap. +- ``"available"`` - amount of memory that can be allocated without extending the swap file(s), in bytes. This value includes both physical memory and swap. -\ ``"stack"`` - size of the current thread stack, in bytes or ``-1`` if unknown. +- ``"stack"`` - size of the current thread stack in bytes. + +\ **Note:** Each entry's value may be ``-1`` if it is unknown. .. rst-class:: classref-item-separator @@ -850,23 +920,23 @@ Returns the model name of the current device. :ref:`String` **get_name** **(** **)** |const| -Returns the name of the host OS. +Returns the name of the host platform. -On Windows, this is ``"Windows"``. +- On Windows, this is ``"Windows"``. -On macOS, this is ``"macOS"``. +- On macOS, this is ``"macOS"``. -On Linux-based operating systems, this is ``"Linux"``. +- On Linux-based operating systems, this is ``"Linux"``. -On BSD-based operating systems, this is ``"FreeBSD"``, ``"NetBSD"``, ``"OpenBSD"``, or ``"BSD"`` as a fallback. +- On BSD-based operating systems, this is ``"FreeBSD"``, ``"NetBSD"``, ``"OpenBSD"``, or ``"BSD"`` as a fallback. -On Android, this is ``"Android"``. +- On Android, this is ``"Android"``. -On iOS, this is ``"iOS"``. +- On iOS, this is ``"iOS"``. -On the web, this is ``"Web"``. +- On the web, this is ``"Web"``. -\ **Note:** Custom builds of the engine may support additional platforms, such as consoles, yielding other return values. +\ **Note:** Custom builds of the engine may support additional platforms, such as consoles, possibly returning other names. .. tabs:: @@ -875,48 +945,50 @@ On the web, this is ``"Web"``. match OS.get_name(): "Windows": - print("Windows") + print("Welcome to Windows!") "macOS": - print("macOS") + print("Welcome to macOS!") "Linux", "FreeBSD", "NetBSD", "OpenBSD", "BSD": - print("Linux/BSD") + print("Welcome to Linux/BSD!") "Android": - print("Android") + print("Welcome to Android!") "iOS": - print("iOS") + print("Welcome to iOS!") "Web": - print("Web") + print("Welcome to the Web!") .. code-tab:: csharp switch (OS.GetName()) { case "Windows": - GD.Print("Windows"); + GD.Print("Welcome to Windows"); break; case "macOS": - GD.Print("macOS"); + GD.Print("Welcome to macOS!"); break; case "Linux": case "FreeBSD": case "NetBSD": case "OpenBSD": case "BSD": - GD.Print("Linux/BSD"); + GD.Print("Welcome to Linux/BSD!"); break; case "Android": - GD.Print("Android"); + GD.Print("Welcome to Android!"); break; case "iOS": - GD.Print("iOS"); + GD.Print("Welcome to iOS!"); break; case "Web": - GD.Print("Web"); + GD.Print("Welcome to the Web!"); break; } +\ **Note:** On Web platforms, it is still possible to determine the host platform's OS with feature tags. See :ref:`has_feature`. + .. rst-class:: classref-item-separator ---- @@ -927,7 +999,7 @@ On the web, this is ``"Web"``. :ref:`int` **get_process_id** **(** **)** |const| -Returns the project's process ID. +Returns the number used by the host machine to uniquely identify this application. \ **Note:** This method is implemented on Android, iOS, Linux, macOS and Windows. @@ -953,7 +1025,7 @@ Returns the number of *logical* CPU cores available on the host machine. On CPUs :ref:`String` **get_processor_name** **(** **)** |const| -Returns the name of the CPU model on the host machine (e.g. "Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz"). +Returns the full name of the CPU model on the host machine (e.g. ``"Intel(R) Core(TM) i7-6700K CPU @ 4.00GHz"``). \ **Note:** This method is only implemented on Windows, macOS, Linux and iOS. On Android and Web, :ref:`get_processor_name` returns an empty string. @@ -979,7 +1051,7 @@ Returns the list of command line arguments that will be used when the project au :ref:`int` **get_static_memory_peak_usage** **(** **)** |const| -Returns the maximum amount of static memory used (only works in debug). +Returns the maximum amount of static memory used. Only works in debug builds. .. rst-class:: classref-item-separator @@ -991,7 +1063,7 @@ Returns the maximum amount of static memory used (only works in debug). :ref:`int` **get_static_memory_usage** **(** **)** |const| -Returns the amount of static memory being used by the program in bytes (only works in debug). +Returns the amount of static memory being used by the program in bytes. Only works in debug builds. .. rst-class:: classref-item-separator @@ -1003,11 +1075,11 @@ Returns the amount of static memory being used by the program in bytes (only wor :ref:`String` **get_system_dir** **(** :ref:`SystemDir` dir, :ref:`bool` shared_storage=true **)** |const| -Returns the actual path to commonly used folders across different platforms. Available locations are specified in :ref:`SystemDir`. +Returns the path to commonly used folders across different platforms, as defined by ``dir``. See the :ref:`SystemDir` constants for available locations. \ **Note:** This method is implemented on Android, Linux, macOS and Windows. -\ **Note:** Shared storage is implemented on Android and allows to differentiate between app specific and shared directories. Shared directories have additional restrictions on Android. +\ **Note:** Shared storage is implemented on Android and allows to differentiate between app specific and shared directories, if ``shared_storage`` is ``true``. Shared directories have additional restrictions on Android. .. rst-class:: classref-item-separator @@ -1019,7 +1091,7 @@ Returns the actual path to commonly used folders across different platforms. Ava :ref:`String` **get_system_font_path** **(** :ref:`String` font_name, :ref:`int` weight=400, :ref:`int` stretch=100, :ref:`bool` italic=false **)** |const| -Returns path to the system font file with ``font_name`` and style. Returns empty string if no matching fonts found. +Returns the path to the system font file with ``font_name`` and style. Returns an empty string if no matching fonts found. The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". @@ -1037,7 +1109,7 @@ The following aliases can be used to request default fonts: "sans-serif", "serif :ref:`PackedStringArray` **get_system_font_path_for_text** **(** :ref:`String` font_name, :ref:`String` text, :ref:`String` locale="", :ref:`String` script="", :ref:`int` weight=400, :ref:`int` stretch=100, :ref:`bool` italic=false **)** |const| -Returns an array of the system substitute font file paths, which are similar to the font with ``font_name`` and style for the specified text, locale and script. Returns empty array if no matching fonts found. +Returns an array of the system substitute font file paths, which are similar to the font with ``font_name`` and style for the specified text, locale, and script. Returns an empty array if no matching fonts found. The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". @@ -1057,7 +1129,7 @@ The following aliases can be used to request default fonts: "sans-serif", "serif :ref:`PackedStringArray` **get_system_fonts** **(** **)** |const| -Returns list of font family names available. +Returns the list of font family names available. \ **Note:** This method is implemented on Android, iOS, Linux, macOS and Windows. @@ -1087,9 +1159,9 @@ Returns the ID of the current thread. This can be used in logs to ease debugging Returns a string that is unique to the device. -\ **Note:** This string may change without notice if the user reinstalls/upgrades their operating system or changes their hardware. This means it should generally not be used to encrypt persistent data as the data saved before an unexpected ID change would become inaccessible. The returned string may also be falsified using external programs, so do not rely on the string returned by :ref:`get_unique_id` for security purposes. +\ **Note:** This string may change without notice if the user reinstalls their operating system, upgrades it, or modifies their hardware. This means it should generally not be used to encrypt persistent data, as the data saved before an unexpected ID change would become inaccessible. The returned string may also be falsified using external programs, so do not rely on the string returned by this method for security purposes. -\ **Note:** Returns an empty string and prints an error on Web, as this method cannot be implemented on this platform. +\ **Note:** On Web, returns an empty string and generates an error, as this method cannot be implemented for security concerns. .. rst-class:: classref-item-separator @@ -1101,17 +1173,17 @@ Returns a string that is unique to the device. :ref:`String` **get_user_data_dir** **(** **)** |const| -Returns the absolute directory path where user data is written (``user://``). +Returns the absolute directory path where user data is written (the ``user://`` directory in Godot). The path depends on the project name and :ref:`ProjectSettings.application/config/use_custom_user_dir`. -On Windows, this is ``%AppData%\Godot\app_userdata\[project_name]``, or ``%AppData%\[custom_name]`` if ``use_custom_user_dir`` is set. ``%AppData%`` expands to ``%UserProfile%\AppData\Roaming``. +- On Windows, this is ``%AppData%\Godot\app_userdata\[project_name]``, or ``%AppData%\[custom_name]`` if ``use_custom_user_dir`` is set. ``%AppData%`` expands to ``%UserProfile%\AppData\Roaming``. -On macOS, this is ``~/Library/Application Support/Godot/app_userdata/[project_name]``, or ``~/Library/Application Support/[custom_name]`` if ``use_custom_user_dir`` is set. +- On macOS, this is ``~/Library/Application Support/Godot/app_userdata/[project_name]``, or ``~/Library/Application Support/[custom_name]`` if ``use_custom_user_dir`` is set. -On Linux and BSD, this is ``~/.local/share/godot/app_userdata/[project_name]``, or ``~/.local/share/[custom_name]`` if ``use_custom_user_dir`` is set. +- On Linux and BSD, this is ``~/.local/share/godot/app_userdata/[project_name]``, or ``~/.local/share/[custom_name]`` if ``use_custom_user_dir`` is set. -On Android and iOS, this is a sandboxed directory in either internal or external storage, depending on the user's configuration. +- On Android and iOS, this is a sandboxed directory in either internal or external storage, depending on the user's configuration. -On the web, this is a virtual directory managed by the browser. +- On Web, this is a virtual directory managed by the browser. If the project name is empty, ``[project_name]`` falls back to ``[unnamed project]``. @@ -1129,15 +1201,15 @@ Not to be confused with :ref:`get_data_dir`, which Returns the exact production and build version of the operating system. This is different from the branded version used in marketing. This helps to distinguish between different releases of operating systems, including minor versions, and insider and custom builds. -For Windows, the major and minor version are returned, as well as the build number. For example, the returned string can look like ``10.0.9926`` for a build of Windows 10, and it can look like ``6.1.7601`` for a build of Windows 7 SP1. +- For Windows, the major and minor version are returned, as well as the build number. For example, the returned string may look like ``10.0.9926`` for a build of Windows 10, and it may look like ``6.1.7601`` for a build of Windows 7 SP1. -For rolling distributions, such as Arch Linux, an empty string is returned. +- For rolling distributions, such as Arch Linux, an empty string is returned. -For macOS and iOS, the major and minor version are returned, as well as the patch number. +- For macOS and iOS, the major and minor version are returned, as well as the patch number. -For Android, the SDK version and the incremental build number are returned. If it's a custom ROM, it attempts to return its version instead. +- For Android, the SDK version and the incremental build number are returned. If it's a custom ROM, it attempts to return its version instead. -\ **Note:** This method is not supported on the web platform. It returns an empty string. +\ **Note:** This method is not supported on the Web platform. It returns an empty string. .. rst-class:: classref-item-separator @@ -1149,13 +1221,13 @@ For Android, the SDK version and the incremental build number are returned. If i :ref:`PackedStringArray` **get_video_adapter_driver_info** **(** **)** |const| -Returns the video adapter driver name and version for the user's currently active graphics card. See also :ref:`RenderingServer.get_video_adapter_api_version`. +Returns the video adapter driver name and version for the user's currently active graphics card, as a :ref:`PackedStringArray`. See also :ref:`RenderingServer.get_video_adapter_api_version`. The first element holds the driver name, such as ``nvidia``, ``amdgpu``, etc. -The second element holds the driver version. For e.g. the ``nvidia`` driver on a Linux/BSD platform, the version is in the format ``510.85.02``. For Windows, the driver's format is ``31.0.15.1659``. +The second element holds the driver version. For example, on the ``nvidia`` driver on a Linux/BSD platform, the version is in the format ``510.85.02``. For Windows, the driver's format is ``31.0.15.1659``. -\ **Note:** This method is only supported on the platforms Linux/BSD and Windows when not running in headless mode. It returns an empty array on other platforms. +\ **Note:** This method is only supported on Linux/BSD and Windows when not running in headless mode. On other platforms, it returns an empty array. .. rst-class:: classref-item-separator @@ -1185,9 +1257,7 @@ Returns ``true`` if the feature for the given feature tag is supported in the cu \ **Note:** Tag names are case-sensitive. -\ **Note:** On the web platform, one of the following additional tags is defined to indicate host platform: ``web_android``, ``web_ios``, ``web_linuxbsd``, ``web_macos``, or ``web_windows``. - -\ **Note:** On the iOS simulator, the additional ``simulator`` tag is defined. +\ **Note:** On the Web platform, one of the following additional tags is defined to indicate host platform: ``web_android``, ``web_ios``, ``web_linuxbsd``, ``web_macos``, or ``web_windows``. .. rst-class:: classref-item-separator @@ -1203,7 +1273,7 @@ Returns ``true`` if the Godot binary used to run the project is a *debug* export Returns ``false`` if the Godot binary used to run the project is a *release* export template. -To check whether the Godot binary used to run the project is an export template (debug or release), use ``OS.has_feature("template")`` instead. +\ **Note:** To check whether the Godot binary used to run the project is an export template (debug or release), use ``OS.has_feature("template")`` instead. .. rst-class:: classref-item-separator @@ -1215,7 +1285,26 @@ To check whether the Godot binary used to run the project is an export template :ref:`bool` **is_keycode_unicode** **(** :ref:`int` code **)** |const| -Returns ``true`` if the input keycode corresponds to a Unicode character. +Returns ``true`` if the input keycode corresponds to a Unicode character. For a list of codes, see the :ref:`Key` constants. + + +.. tabs:: + + .. code-tab:: gdscript + + print(OS.is_keycode_unicode(KEY_G)) # Prints true + print(OS.is_keycode_unicode(KEY_KP_4)) # Prints true + print(OS.is_keycode_unicode(KEY_TAB)) # Prints false + print(OS.is_keycode_unicode(KEY_ESCAPE)) # Prints false + + .. code-tab:: csharp + + GD.Print(OS.IsKeycodeUnicode((long)Key.G)); // Prints true + GD.Print(OS.IsKeycodeUnicode((long)Key.Kp4)); // Prints true + GD.Print(OS.IsKeycodeUnicode((long)Key.Tab)); // Prints false + GD.Print(OS.IsKeycodeUnicode((long)Key.Escape)); // Prints false + + .. rst-class:: classref-item-separator @@ -1227,9 +1316,7 @@ Returns ``true`` if the input keycode corresponds to a Unicode character. :ref:`bool` **is_process_running** **(** :ref:`int` pid **)** |const| -Returns ``true`` if the child process ID (``pid``) is still running or ``false`` if it has terminated. - -Must be a valid ID generated from :ref:`create_process`. +Returns ``true`` if the child process ID (``pid``) is still running or ``false`` if it has terminated. ``pid`` must be a valid ID generated from :ref:`create_process`. \ **Note:** This method is implemented on Android, iOS, Linux, macOS and Windows. @@ -1255,9 +1342,9 @@ Returns ``true`` if the project will automatically restart when it exits for any :ref:`bool` **is_sandboxed** **(** **)** |const| -Returns ``true`` if application is running in the sandbox. +Returns ``true`` if the application is running in the sandbox. -\ **Note:** This method is implemented on macOS and Linux. +\ **Note:** This method is only implemented on macOS and Linux. .. rst-class:: classref-item-separator @@ -1281,7 +1368,7 @@ Returns ``true`` if the engine was executed with the ``--verbose`` or ``-v`` com :ref:`bool` **is_userfs_persistent** **(** **)** |const| -If ``true``, the ``user://`` file system is persistent, so that its state is the same after a player quits and starts the game again. Relevant to the Web platform, where this persistence may be unavailable. +Returns ``true`` if the ``user://`` file system is persistent, that is, its state is the same after a player quits and starts the game again. Relevant to the Web platform, where this persistence may be unavailable. .. rst-class:: classref-item-separator @@ -1293,9 +1380,9 @@ If ``true``, the ``user://`` file system is persistent, so that its state is the :ref:`Error` **kill** **(** :ref:`int` pid **)** -Kill (terminate) the process identified by the given process ID (``pid``), e.g. the one returned by :ref:`execute` in non-blocking mode. See also :ref:`crash`. +Kill (terminate) the process identified by the given process ID (``pid``), such as the ID returned by :ref:`execute` in non-blocking mode. See also :ref:`crash`. -\ **Note:** This method can also be used to kill processes that were not spawned by the game. +\ **Note:** This method can also be used to kill processes that were not spawned by the engine. \ **Note:** This method is implemented on Android, iOS, Linux, macOS and Windows. @@ -1309,11 +1396,11 @@ Kill (terminate) the process identified by the given process ID (``pid``), e.g. :ref:`Error` **move_to_trash** **(** :ref:`String` path **)** |const| -Moves the file or directory to the system's recycle bin. See also :ref:`DirAccess.remove`. +Moves the file or directory at the given ``path`` to the system's recycle bin. See also :ref:`DirAccess.remove`. The method takes only global paths, so you may need to use :ref:`ProjectSettings.globalize_path`. Do not use it for files in ``res://`` as it will not work in exported projects. -\ **Note:** If the user has disabled the recycle bin on their system, the file will be permanently deleted instead. +Returns :ref:`@GlobalScope.FAILED` if the file or directory cannot be found, or the system does not support this method. .. tabs:: @@ -1330,6 +1417,10 @@ The method takes only global paths, so you may need to use :ref:`ProjectSettings +\ **Note:** This method is implemented on Android, Linux, macOS and Windows. + +\ **Note:** If the user has disabled the recycle bin on their system, the file will be permanently deleted instead. + .. rst-class:: classref-item-separator ---- @@ -1340,7 +1431,7 @@ The method takes only global paths, so you may need to use :ref:`ProjectSettings void **open_midi_inputs** **(** **)** -Initializes the singleton for the system MIDI driver. +Initializes the singleton for the system MIDI driver, allowing Godot to receive :ref:`InputEventMIDI`. See also :ref:`get_connected_midi_inputs` and :ref:`close_midi_inputs`. \ **Note:** This method is implemented on Linux, macOS and Windows. @@ -1368,7 +1459,9 @@ Reads a user input string from the standard input (usually the terminal). This o :ref:`bool` **request_permission** **(** :ref:`String` name **)** -At the moment this function is only used by ``AudioDriverOpenSL`` to request permission for ``RECORD_AUDIO`` on Android. +Requests permission from the OS for the given ``name``. Returns ``true`` if the permission has been successfully granted. + +\ **Note:** This method is currently only implemented on Android, to specifically request permission for ``"RECORD_AUDIO"`` by ``AudioDriverOpenSL``. .. rst-class:: classref-item-separator @@ -1380,9 +1473,9 @@ At the moment this function is only used by ``AudioDriverOpenSL`` to request per :ref:`bool` **request_permissions** **(** **)** -With this function, you can request dangerous permissions since normal permissions are automatically granted at install time in Android applications. +Requests *dangerous* permissions from the OS. Returns ``true`` if permissions have been successfully granted. -\ **Note:** This method is implemented only on Android. +\ **Note:** This method is only implemented on Android. Normal permissions are automatically granted at install time in Android applications. .. rst-class:: classref-item-separator @@ -1420,9 +1513,9 @@ Sets the value of the environment variable ``variable`` to ``value``. The enviro void **set_restart_on_exit** **(** :ref:`bool` restart, :ref:`PackedStringArray` arguments=PackedStringArray() **)** -If ``restart`` is ``true``, restarts the project automatically when it is exited with :ref:`SceneTree.quit` or :ref:`Node.NOTIFICATION_WM_CLOSE_REQUEST`. Command line ``arguments`` can be supplied. To restart the project with the same command line arguments as originally used to run the project, pass :ref:`get_cmdline_args` as the value for ``arguments``. +If ``restart`` is ``true``, restarts the project automatically when it is exited with :ref:`SceneTree.quit` or :ref:`Node.NOTIFICATION_WM_CLOSE_REQUEST`. Command-line ``arguments`` can be supplied. To restart the project with the same command line arguments as originally used to run the project, pass :ref:`get_cmdline_args` as the value for ``arguments``. -\ :ref:`set_restart_on_exit` can be used to apply setting changes that require a restart. See also :ref:`is_restart_on_exit_set` and :ref:`get_restart_on_exit_arguments`. +This method can be used to apply setting changes that require a restart. See also :ref:`is_restart_on_exit_set` and :ref:`get_restart_on_exit_arguments`. \ **Note:** This method is only effective on desktop platforms, and only when the project isn't started from the editor. It will have no effect on mobile and Web platforms, or when the project is started from the editor. @@ -1438,7 +1531,7 @@ If ``restart`` is ``true``, restarts the project automatically when it is exited :ref:`Error` **set_thread_name** **(** :ref:`String` name **)** -Sets the name of the current thread. +Assigns the given name to the current thread. Returns :ref:`@GlobalScope.ERR_UNAVAILABLE` if unavailable on the current platform. .. rst-class:: classref-item-separator @@ -1450,7 +1543,9 @@ Sets the name of the current thread. void **set_use_file_access_save_and_swap** **(** :ref:`bool` enabled **)** -Enables backup saves if ``enabled`` is ``true``. +If ``enabled`` is ``true``, when opening a file for writing, a temporary file is used in its place. When closed, it is automatically applied to the target file. + +This can useful when files may be opened by other applications, such as antiviruses, text editors, or even the Godot editor itself. .. rst-class:: classref-item-separator @@ -1462,7 +1557,7 @@ Enables backup saves if ``enabled`` is ``true``. :ref:`Error` **shell_open** **(** :ref:`String` uri **)** -Requests the OS to open a resource with the most appropriate program. For example: +Requests the OS to open a resource identified by ``uri`` with the most appropriate program. For example: - ``OS.shell_open("C:\\Users\name\Downloads")`` on Windows opens the file explorer at the user's Downloads folder. @@ -1470,7 +1565,7 @@ Requests the OS to open a resource with the most appropriate program. For exampl - ``OS.shell_open("mailto:example@example.com")`` opens the default email client with the "To" field set to ``example@example.com``. See `RFC 2368 - The [code]mailto[/code] URL scheme `__ for a list of fields that can be added. -Use :ref:`ProjectSettings.globalize_path` to convert a ``res://`` or ``user://`` path into a system path for use with this method. +Use :ref:`ProjectSettings.globalize_path` to convert a ``res://`` or ``user://`` project path into a system path for use with this method. \ **Note:** Use :ref:`String.uri_encode` to encode characters within URLs in a URL-safe, portable way. This is especially required for line breaks. Otherwise, :ref:`shell_open` may not work correctly in a project exported to the Web platform. @@ -1486,13 +1581,13 @@ Use :ref:`ProjectSettings.globalize_path` **shell_show_in_file_manager** **(** :ref:`String` file_or_dir_path, :ref:`bool` open_folder=true **)** -Requests the OS to open the file manager, then navigate to the given ``file_or_dir_path`` and select the target file or folder. +Requests the OS to open the file manager, navigate to the given ``file_or_dir_path`` and select the target file or folder. -If ``file_or_dir_path`` is a valid directory path, and ``open_folder`` is ``true``, the method will open the file manager and enter the target folder without selecting anything. +If ``open_folder`` is ``true`` and ``file_or_dir_path`` is a valid directory path, the OS will open the file manager and navigate to the target folder without selecting anything. -Use :ref:`ProjectSettings.globalize_path` to convert a ``res://`` or ``user://`` path into a system path for use with this method. +Use :ref:`ProjectSettings.globalize_path` to convert a ``res://`` or ``user://`` project path into a system path to use with this method. -\ **Note:** Currently this method is only implemented on Windows and macOS. On other platforms, it will fallback to :ref:`shell_open` with a directory path of ``file_or_dir_path`` with prefix ``file://``. +\ **Note:** This method is currently only implemented on Windows and macOS. On other platforms, it will fallback to :ref:`shell_open` with a directory path of ``file_or_dir_path`` prefixed with ``file://``. .. rst-class:: classref-item-separator @@ -1504,9 +1599,9 @@ Use :ref:`ProjectSettings.globalize_path` variable **)** |const| -Removes the environment ``variable`` from the current environment, if it exists. The environment variable will be removed for the Godot process and any process executed with :ref:`execute` after running :ref:`unset_environment`. The removal of the environment variable will *not* persist to processes run after the Godot process was terminated. +Removes the given environment variable from the current environment, if it exists. The ``variable`` name cannot be empty or include the ``=`` character. The environment variable will be removed for the Godot process and any process executed with :ref:`execute` after running :ref:`unset_environment`. The removal of the environment variable will *not* persist to processes run after the Godot process was terminated. -\ **Note:** Environment variable names are case-sensitive on all platforms except Windows. The ``variable`` name cannot be empty or include the ``=`` character. +\ **Note:** Environment variable names are case-sensitive on all platforms except Windows. .. |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_packedbytearray.rst b/classes/class_packedbytearray.rst index ef3301ba4f4..009cb56b53f 100644 --- a/classes/class_packedbytearray.rst +++ b/classes/class_packedbytearray.rst @@ -836,7 +836,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedcolorarray.rst b/classes/class_packedcolorarray.rst index 4f44ff7721d..93ff37a789c 100644 --- a/classes/class_packedcolorarray.rst +++ b/classes/class_packedcolorarray.rst @@ -325,7 +325,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedfloat32array.rst b/classes/class_packedfloat32array.rst index 6244485388e..631ec722a7b 100644 --- a/classes/class_packedfloat32array.rst +++ b/classes/class_packedfloat32array.rst @@ -329,7 +329,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedfloat64array.rst b/classes/class_packedfloat64array.rst index 4020f7a7b14..7a2ba0512a7 100644 --- a/classes/class_packedfloat64array.rst +++ b/classes/class_packedfloat64array.rst @@ -329,7 +329,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedint32array.rst b/classes/class_packedint32array.rst index e5e4dfa230e..24144df2108 100644 --- a/classes/class_packedint32array.rst +++ b/classes/class_packedint32array.rst @@ -321,7 +321,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedint64array.rst b/classes/class_packedint64array.rst index 8b710ef908d..419993dafa0 100644 --- a/classes/class_packedint64array.rst +++ b/classes/class_packedint64array.rst @@ -321,7 +321,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedstringarray.rst b/classes/class_packedstringarray.rst index b623f3e9ec0..aa6b65605f7 100644 --- a/classes/class_packedstringarray.rst +++ b/classes/class_packedstringarray.rst @@ -334,7 +334,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedvector2array.rst b/classes/class_packedvector2array.rst index d41288c9db4..1f961c694eb 100644 --- a/classes/class_packedvector2array.rst +++ b/classes/class_packedvector2array.rst @@ -342,7 +342,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_packedvector3array.rst b/classes/class_packedvector3array.rst index 98bc0ead1d4..d2e7b0e3fb1 100644 --- a/classes/class_packedvector3array.rst +++ b/classes/class_packedvector3array.rst @@ -335,7 +335,7 @@ Removes an element from the array by index. :ref:`int` **resize** **(** :ref:`int` new_size **)** -Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. +Sets the size of the array. If the array is grown, reserves elements at the end of the array. If the array is shrunk, truncates the array to the new size. Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. .. rst-class:: classref-item-separator diff --git a/classes/class_panoramaskymaterial.rst b/classes/class_panoramaskymaterial.rst index d1208073531..865d2dfa9cd 100644 --- a/classes/class_panoramaskymaterial.rst +++ b/classes/class_panoramaskymaterial.rst @@ -33,11 +33,13 @@ Properties .. table:: :widths: auto - +-----------------------------------+--------------------------------------------------------------+----------+ - | :ref:`bool` | :ref:`filter` | ``true`` | - +-----------------------------------+--------------------------------------------------------------+----------+ - | :ref:`Texture2D` | :ref:`panorama` | | - +-----------------------------------+--------------------------------------------------------------+----------+ + +-----------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`energy_multiplier` | ``1.0`` | + +-----------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`filter` | ``true`` | + +-----------------------------------+--------------------------------------------------------------------------------+----------+ + | :ref:`Texture2D` | :ref:`panorama` | | + +-----------------------------------+--------------------------------------------------------------------------------+----------+ .. rst-class:: classref-section-separator @@ -48,6 +50,23 @@ Properties Property Descriptions --------------------- +.. _class_PanoramaSkyMaterial_property_energy_multiplier: + +.. rst-class:: classref-property + +:ref:`float` **energy_multiplier** = ``1.0`` + +.. rst-class:: classref-property-setget + +- void **set_energy_multiplier** **(** :ref:`float` value **)** +- :ref:`float` **get_energy_multiplier** **(** **)** + +The sky's overall brightness multiplier. Higher values result in a brighter sky. + +.. rst-class:: classref-item-separator + +---- + .. _class_PanoramaSkyMaterial_property_filter: .. rst-class:: classref-property diff --git a/classes/class_particleprocessmaterial.rst b/classes/class_particleprocessmaterial.rst index 388999bff1c..1bf60d93f7e 100644 --- a/classes/class_particleprocessmaterial.rst +++ b/classes/class_particleprocessmaterial.rst @@ -227,6 +227,8 @@ Methods .. table:: :widths: auto + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_param` **(** :ref:`Parameter` param **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_param_max` **(** :ref:`Parameter` param **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -236,6 +238,8 @@ Methods +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`get_particle_flag` **(** :ref:`ParticleFlags` particle_flag **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_param` **(** :ref:`Parameter` param, :ref:`Vector2` value **)** | + +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_param_max` **(** :ref:`Parameter` param, :ref:`float` value **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_param_min` **(** :ref:`Parameter` param, :ref:`float` value **)** | @@ -2306,6 +2310,20 @@ A pivot point used to calculate radial and orbital velocity of particles. Method Descriptions ------------------- +.. _class_ParticleProcessMaterial_method_get_param: + +.. rst-class:: classref-method + +:ref:`Vector2` **get_param** **(** :ref:`Parameter` param **)** |const| + +Returns the minimum and maximum values of the given ``param`` as a vector. + +The ``x`` component of the returned vector corresponds to minimum and the ``y`` component corresponds to maximum. + +.. rst-class:: classref-item-separator + +---- + .. _class_ParticleProcessMaterial_method_get_param_max: .. rst-class:: classref-method @@ -2354,6 +2372,20 @@ Returns ``true`` if the specified particle flag is enabled. See :ref:`ParticleFl ---- +.. _class_ParticleProcessMaterial_method_set_param: + +.. rst-class:: classref-method + +void **set_param** **(** :ref:`Parameter` param, :ref:`Vector2` value **)** + +Sets the minimum and maximum values of the given ``param``. + +The ``x`` component of the argument vector corresponds to minimum and the ``y`` component corresponds to maximum. + +.. rst-class:: classref-item-separator + +---- + .. _class_ParticleProcessMaterial_method_set_param_max: .. rst-class:: classref-method diff --git a/classes/class_popupmenu.rst b/classes/class_popupmenu.rst index ae8b6dfcd23..1370b9b58cc 100644 --- a/classes/class_popupmenu.rst +++ b/classes/class_popupmenu.rst @@ -37,19 +37,21 @@ Properties .. table:: :widths: auto - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`allow_search` | ``true`` | - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`hide_on_checkable_item_selection` | ``true`` | - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`hide_on_item_selection` | ``true`` | - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`hide_on_state_item_selection` | ``false`` | - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ - | :ref:`int` | :ref:`item_count` | ``0`` | - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ - | :ref:`float` | :ref:`submenu_popup_delay` | ``0.3`` | - +---------------------------+----------------------------------------------------------------------------------------------------+-----------+ + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`allow_search` | ``true`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`hide_on_checkable_item_selection` | ``true`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`hide_on_item_selection` | ``true`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`hide_on_state_item_selection` | ``false`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`item_count` | ``0`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`submenu_popup_delay` | ``0.3`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`system_menu_root` | ``""`` | + +-----------------------------+----------------------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group @@ -136,6 +138,8 @@ Methods +--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_item_shortcut_disabled` **(** :ref:`int` index **)** |const| | +--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_system_menu` **(** **)** |const| | + +--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_item` **(** :ref:`int` index **)** | +--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`scroll_to_item` **(** :ref:`int` index **)** | @@ -425,6 +429,23 @@ The number of items currently in the list. Sets the delay time in seconds for the submenu item to popup on mouse hovering. If the popup menu is added as a child of another (acting as a submenu), it will inherit the delay time of the parent menu item. +.. rst-class:: classref-item-separator + +---- + +.. _class_PopupMenu_property_system_menu_root: + +.. rst-class:: classref-property + +:ref:`String` **system_menu_root** = ``""`` + +.. rst-class:: classref-property-setget + +- void **set_system_menu_root** **(** :ref:`String` value **)** +- :ref:`String` **get_system_menu_root** **(** **)** + +If set to one of the values returned by :ref:`DisplayServer.global_menu_get_system_menu_roots`, this **PopupMenu** is bound to the special system menu. Only one **PopupMenu** can be bound to each special menu at a time. + .. rst-class:: classref-section-separator ---- @@ -946,6 +967,18 @@ Returns ``true`` if the specified item's shortcut is disabled. ---- +.. _class_PopupMenu_method_is_system_menu: + +.. rst-class:: classref-method + +:ref:`bool` **is_system_menu** **(** **)** |const| + +Returns ``true`` if the menu is bound to the special system menu. + +.. rst-class:: classref-item-separator + +---- + .. _class_PopupMenu_method_remove_item: .. rst-class:: classref-method diff --git a/classes/class_proceduralskymaterial.rst b/classes/class_proceduralskymaterial.rst index 33002aeb0ef..8fd0a149810 100644 --- a/classes/class_proceduralskymaterial.rst +++ b/classes/class_proceduralskymaterial.rst @@ -33,6 +33,8 @@ Properties .. table:: :widths: auto + +-----------------------------------+------------------------------------------------------------------------------------------------+--------------------------------------+ + | :ref:`float` | :ref:`energy_multiplier` | ``1.0`` | +-----------------------------------+------------------------------------------------------------------------------------------------+--------------------------------------+ | :ref:`Color` | :ref:`ground_bottom_color` | ``Color(0.2, 0.169, 0.133, 1)`` | +-----------------------------------+------------------------------------------------------------------------------------------------+--------------------------------------+ @@ -70,6 +72,23 @@ Properties Property Descriptions --------------------- +.. _class_ProceduralSkyMaterial_property_energy_multiplier: + +.. rst-class:: classref-property + +:ref:`float` **energy_multiplier** = ``1.0`` + +.. rst-class:: classref-property-setget + +- void **set_energy_multiplier** **(** :ref:`float` value **)** +- :ref:`float` **get_energy_multiplier** **(** **)** + +The sky's overall brightness multiplier. Higher values result in a brighter sky. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProceduralSkyMaterial_property_ground_bottom_color: .. rst-class:: classref-property diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 6236f903fb1..a6bdc084d75 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -1113,8 +1113,6 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`memory/limits/message_queue/max_size_mb` | ``32`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`memory/limits/multithreaded_server/rid_pool_prealloc` | ``60`` | - +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`navigation/2d/default_cell_size` | ``1.0`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`navigation/2d/default_edge_connection_margin` | ``1.0`` | @@ -1405,8 +1403,6 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`rendering/limits/cluster_builder/max_clustered_elements` | ``512`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`rendering/limits/forward_renderer/threaded_render_minimum_instances` | ``500`` | - +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/limits/global_shader_variables/buffer_size` | ``65536`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/limits/opengl/max_lights_per_object` | ``8`` | @@ -1453,6 +1449,14 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/renderer/rendering_method.web` | ``"gl_compatibility"`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rendering/rendering_device/d3d12/agility_sdk_version` | ``610`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rendering/rendering_device/d3d12/max_misc_descriptors_per_frame` | ``512`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rendering/rendering_device/d3d12/max_resource_descriptors_per_frame` | ``16384`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rendering/rendering_device/d3d12/max_sampler_descriptors_per_frame` | ``1024`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/rendering_device/driver` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/rendering_device/driver.android` | | @@ -1535,8 +1539,6 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`threading/worker_pool/max_threads` | ``-1`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`threading/worker_pool/use_system_threads_for_low_priority_tasks` | ``true`` | - +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`xr/openxr/default_action_map` | ``"res://openxr_action_map.tres"`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`xr/openxr/enabled` | ``false`` | @@ -3834,7 +3836,11 @@ Main window can't be focused. No-focus window will ignore all input, except mous :ref:`bool` **display/window/size/resizable** = ``true`` -Allows the window to be resizable by default. +If ``true``, allows the window to be resizable by default. + +\ **Note:** This property is only read when the project starts. To change whether the window is resizable at runtime, set :ref:`Window.unresizable` instead on the root Window, which can be retrieved using ``get_viewport().get_window()``. :ref:`Window.unresizable` takes the opposite value of this setting. + +\ **Note:** Certain window managers can be configured to ignore the non-resizable status of a window. Do not rely on this setting as a guarantee that the window will *never* be resizable. \ **Note:** This setting is ignored on iOS. @@ -4928,7 +4934,7 @@ Default :ref:`InputEventAction` to select an item in a : :ref:`Dictionary` **input/ui_swap_input_direction** -Default :ref:`InputEventAction` to swap input direction, i.e. change between left-to-right to right-to-left modes. Affects text-editting controls (:ref:`LineEdit`, :ref:`TextEdit`). +Default :ref:`InputEventAction` to swap input direction, i.e. change between left-to-right to right-to-left modes. Affects text-editing controls (:ref:`LineEdit`, :ref:`TextEdit`). .. rst-class:: classref-item-separator @@ -5330,7 +5336,7 @@ In case there's more than one caret active, removes the secondary carets and cle :ref:`Dictionary` **input/ui_text_completion_accept** -Default :ref:`InputEventAction` to accept an autocompetion hint. +Default :ref:`InputEventAction` to accept an autocompletion hint. \ **Note:** Default ``ui_*`` actions cannot be removed as they are necessary for the internal logic of several :ref:`Control`\ s. The events assigned to the action can however be modified. @@ -5344,7 +5350,7 @@ Default :ref:`InputEventAction` to accept an autocompeti :ref:`Dictionary` **input/ui_text_completion_query** -Default :ref:`InputEventAction` to request autocompetion. +Default :ref:`InputEventAction` to request autocompletion. \ **Note:** Default ``ui_*`` actions cannot be removed as they are necessary for the internal logic of several :ref:`Control`\ s. The events assigned to the action can however be modified. @@ -5358,7 +5364,7 @@ Default :ref:`InputEventAction` to request autocompetion :ref:`Dictionary` **input/ui_text_completion_replace** -Default :ref:`InputEventAction` to accept an autocompetion hint, replacing existing text. +Default :ref:`InputEventAction` to accept an autocompletion hint, replacing existing text. \ **Note:** Default ``ui_*`` actions cannot be removed as they are necessary for the internal logic of several :ref:`Control`\ s. The events assigned to the action can however be modified. @@ -8362,18 +8368,6 @@ Godot uses a message queue to defer some function calls. If you run out of space ---- -.. _class_ProjectSettings_property_memory/limits/multithreaded_server/rid_pool_prealloc: - -.. rst-class:: classref-property - -:ref:`int` **memory/limits/multithreaded_server/rid_pool_prealloc** = ``60`` - -This is used by servers when used in multi-threading mode (servers and visual). RIDs are preallocated to avoid stalling the server requesting them on threads. If servers get stalled too often when loading resources in a thread, increase this number. - -.. rst-class:: classref-item-separator - ----- - .. _class_ProjectSettings_property_navigation/2d/default_cell_size: .. rst-class:: classref-property @@ -10306,20 +10300,6 @@ Decreasing this value may improve GPU performance on certain setups, even if the ---- -.. _class_ProjectSettings_property_rendering/limits/forward_renderer/threaded_render_minimum_instances: - -.. rst-class:: classref-property - -:ref:`int` **rendering/limits/forward_renderer/threaded_render_minimum_instances** = ``500`` - -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! - -.. rst-class:: classref-item-separator - ----- - .. _class_ProjectSettings_property_rendering/limits/global_shader_variables/buffer_size: .. rst-class:: classref-property @@ -10628,6 +10608,60 @@ Override for :ref:`rendering/renderer/rendering_method` **rendering/rendering_device/d3d12/agility_sdk_version** = ``610`` + +Version code of the Direct3D 12 Agility SDK to use (``D3D12SDKVersion``). + +.. rst-class:: classref-item-separator + +---- + +.. _class_ProjectSettings_property_rendering/rendering_device/d3d12/max_misc_descriptors_per_frame: + +.. rst-class:: classref-property + +:ref:`int` **rendering/rendering_device/d3d12/max_misc_descriptors_per_frame** = ``512`` + +The number of entries in the miscellaneous descriptors heap the Direct3D 12 rendering driver uses each frame, used for various operations like clearing a texture. + +Depending on the complexity of scenes, this value may be lowered or may need to be raised. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ProjectSettings_property_rendering/rendering_device/d3d12/max_resource_descriptors_per_frame: + +.. rst-class:: classref-property + +:ref:`int` **rendering/rendering_device/d3d12/max_resource_descriptors_per_frame** = ``16384`` + +The number of entries in the resource descriptors heap the Direct3D 12 rendering driver uses each frame, used for most rendering operations. + +Depending on the complexity of scenes, this value may be lowered or may need to be raised. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ProjectSettings_property_rendering/rendering_device/d3d12/max_sampler_descriptors_per_frame: + +.. rst-class:: classref-property + +:ref:`int` **rendering/rendering_device/d3d12/max_sampler_descriptors_per_frame** = ``1024`` + +The number of entries in the sampler descriptors heap the Direct3D 12 rendering driver uses each frame, used for most rendering operations. + +Depending on the complexity of scenes, this value may be lowered or may need to be raised. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_property_rendering/rendering_device/driver: .. rst-class:: classref-property @@ -11179,20 +11213,6 @@ Maximum number of threads to be used by :ref:`WorkerThreadPool` **threading/worker_pool/use_system_threads_for_low_priority_tasks** = ``true`` - -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! - -.. rst-class:: classref-item-separator - ----- - .. _class_ProjectSettings_property_xr/openxr/default_action_map: .. rst-class:: classref-property @@ -11273,6 +11293,8 @@ Specify whether OpenXR should be configured for an HMD or a hand held device. If true and foveation is supported, will automatically adjust foveation level based on framerate up to the level set on :ref:`xr/openxr/foveation_level`. +\ **Note:** Only works on compatibility renderer. + .. rst-class:: classref-item-separator ---- @@ -11285,6 +11307,8 @@ If true and foveation is supported, will automatically adjust foveation level ba Applied foveation level if supported: 0 = off, 1 = low, 2 = medium, 3 = high. +\ **Note:** Only works on compatibility renderer. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_quaternion.rst b/classes/class_quaternion.rst index 6991799216d..edbc3c40647 100644 --- a/classes/class_quaternion.rst +++ b/classes/class_quaternion.rst @@ -346,9 +346,7 @@ Returns the dot product of two quaternions. :ref:`Quaternion` **exp** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the exponential of this quaternion. The rotation axis of the result is the normalized rotation axis of this quaternion, the angle of the result is the length of the vector part of this quaternion. .. rst-class:: classref-item-separator @@ -372,9 +370,9 @@ Constructs a Quaternion from Euler angles in YXZ rotation order. :ref:`float` **get_angle** **(** **)** |const| -.. container:: contribute +Returns the angle of the rotation represented by this quaternion. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ **Note:** The quaternion must be normalized. .. rst-class:: classref-item-separator @@ -386,9 +384,7 @@ Constructs a Quaternion from Euler angles in YXZ rotation order. :ref:`Vector3` **get_axis** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the rotation axis of the rotation represented by this quaternion. .. rst-class:: classref-item-separator @@ -484,9 +480,7 @@ Returns the length of the quaternion, squared. :ref:`Quaternion` **log** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the logarithm of this quaternion. The vector part of the result is the rotation axis of this quaternion multiplied by its rotation angle, the real part of the result is zero. .. rst-class:: classref-item-separator diff --git a/classes/class_rduniform.rst b/classes/class_rduniform.rst index 8d55f14a34e..5df37ab665a 100644 --- a/classes/class_rduniform.rst +++ b/classes/class_rduniform.rst @@ -105,9 +105,7 @@ Method Descriptions void **add_id** **(** :ref:`RID` id **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Binds the given id to the uniform. The data associated with the id is then used when the uniform is passed to a shader. .. rst-class:: classref-item-separator @@ -119,9 +117,7 @@ void **add_id** **(** :ref:`RID` id **)** void **clear_ids** **(** **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Unbinds all ids currently bound to the uniform. .. rst-class:: classref-item-separator @@ -133,9 +129,7 @@ void **clear_ids** **(** **)** :ref:`RID[]` **get_ids** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns an array of all ids currently bound to the uniform. .. |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_renderingdevice.rst b/classes/class_renderingdevice.rst index f55afd4f8f0..482ac9cd93d 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -47,17 +47,19 @@ Methods +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`barrier` **(** |bitfield|\<:ref:`BarrierMask`\> from=32767, |bitfield|\<:ref:`BarrierMask`\> to=32767 **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`buffer_clear` **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | :ref:`Error` | :ref:`buffer_clear` **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes **)** | + +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`buffer_copy` **(** :ref:`RID` src_buffer, :ref:`RID` dst_buffer, :ref:`int` src_offset, :ref:`int` dst_offset, :ref:`int` size **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :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, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | :ref:`Error` | :ref:`buffer_update` **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, :ref:`PackedByteArray` data **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`capture_timestamp` **(** :ref:`String` name **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`compute_list_add_barrier` **(** :ref:`int` compute_list **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`compute_list_begin` **(** :ref:`bool` allow_draw_overlap=false **)** | + | :ref:`int` | :ref:`compute_list_begin` **(** **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`compute_list_bind_compute_pipeline` **(** :ref:`int` compute_list, :ref:`RID` compute_pipeline **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -65,7 +67,7 @@ Methods +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`compute_list_dispatch` **(** :ref:`int` compute_list, :ref:`int` x_groups, :ref:`int` y_groups, :ref:`int` z_groups **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`compute_list_end` **(** |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | void | :ref:`compute_list_end` **(** **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`compute_list_set_push_constant` **(** :ref:`int` compute_list, :ref:`PackedByteArray` buffer, :ref:`int` size_bytes **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -81,7 +83,7 @@ Methods +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`draw_command_insert_label` **(** :ref:`String` name, :ref:`Color` color **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`draw_list_begin` **(** :ref:`RID` framebuffer, :ref:`InitialAction` initial_color_action, :ref:`FinalAction` final_color_action, :ref:`InitialAction` initial_depth_action, :ref:`FinalAction` final_depth_action, :ref:`PackedColorArray` clear_color_values=PackedColorArray(), :ref:`float` clear_depth=1.0, :ref:`int` clear_stencil=0, :ref:`Rect2` region=Rect2(0, 0, 0, 0), :ref:`RID[]` storage_textures=[] **)** | + | :ref:`int` | :ref:`draw_list_begin` **(** :ref:`RID` framebuffer, :ref:`InitialAction` initial_color_action, :ref:`FinalAction` final_color_action, :ref:`InitialAction` initial_depth_action, :ref:`FinalAction` final_depth_action, :ref:`PackedColorArray` clear_color_values=PackedColorArray(), :ref:`float` clear_depth=1.0, :ref:`int` clear_stencil=0, :ref:`Rect2` region=Rect2(0, 0, 0, 0) **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`draw_list_begin_for_screen` **(** :ref:`int` screen=0, :ref:`Color` clear_color=Color(0, 0, 0, 1) **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -101,7 +103,7 @@ Methods +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`draw_list_enable_scissor` **(** :ref:`int` draw_list, :ref:`Rect2` rect=Rect2(0, 0, 0, 0) **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`draw_list_end` **(** |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | void | :ref:`draw_list_end` **(** **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`draw_list_set_blend_constants` **(** :ref:`int` draw_list, :ref:`Color` color **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -197,9 +199,9 @@ Methods +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`texture_buffer_create` **(** :ref:`int` size_bytes, :ref:`DataFormat` format, :ref:`PackedByteArray` data=PackedByteArray() **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`texture_clear` **(** :ref:`RID` texture, :ref:`Color` color, :ref:`int` base_mipmap, :ref:`int` mipmap_count, :ref:`int` base_layer, :ref:`int` layer_count, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | :ref:`Error` | :ref:`texture_clear` **(** :ref:`RID` texture, :ref:`Color` color, :ref:`int` base_mipmap, :ref:`int` mipmap_count, :ref:`int` base_layer, :ref:`int` layer_count **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`texture_copy` **(** :ref:`RID` from_texture, :ref:`RID` to_texture, :ref:`Vector3` from_pos, :ref:`Vector3` to_pos, :ref:`Vector3` size, :ref:`int` src_mipmap, :ref:`int` dst_mipmap, :ref:`int` src_layer, :ref:`int` dst_layer, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | :ref:`Error` | :ref:`texture_copy` **(** :ref:`RID` from_texture, :ref:`RID` to_texture, :ref:`Vector3` from_pos, :ref:`Vector3` to_pos, :ref:`Vector3` size, :ref:`int` src_mipmap, :ref:`int` dst_mipmap, :ref:`int` src_layer, :ref:`int` dst_layer **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`texture_create` **(** :ref:`RDTextureFormat` format, :ref:`RDTextureView` view, :ref:`PackedByteArray[]` data=[] **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -221,9 +223,9 @@ Methods +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`texture_is_valid` **(** :ref:`RID` texture **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`texture_resolve_multisample` **(** :ref:`RID` from_texture, :ref:`RID` to_texture, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | :ref:`Error` | :ref:`texture_resolve_multisample` **(** :ref:`RID` from_texture, :ref:`RID` to_texture **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`texture_update` **(** :ref:`RID` texture, :ref:`int` layer, :ref:`PackedByteArray` data, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** | + | :ref:`Error` | :ref:`texture_update` **(** :ref:`RID` texture, :ref:`int` layer, :ref:`PackedByteArray` data **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`uniform_buffer_create` **(** :ref:`int` size_bytes, :ref:`PackedByteArray` data=PackedByteArray() **)** | +------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -311,13 +313,133 @@ Represents the size of the :ref:`DeviceType` en enum **DriverResource**: +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_LOGICAL_DEVICE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_LOGICAL_DEVICE** = ``0`` + +Specific device object based on a physical device. + +- Vulkan: Vulkan device driver resource (``VkDevice``). (``rid`` argument doesn't apply.) + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_PHYSICAL_DEVICE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_PHYSICAL_DEVICE** = ``1`` + +Physical device the specific logical device is based on. + +- Vulkan: ``VkDevice``. (``rid`` argument doesn't apply.) + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_TOPMOST_OBJECT: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_TOPMOST_OBJECT** = ``2`` + +Top-most graphics API entry object. + +- Vulkan: ``VkInstance``. (``rid`` argument doesn't apply.) + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_COMMAND_QUEUE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_COMMAND_QUEUE** = ``3`` + +The main graphics-compute command queue. + +- Vulkan: ``VkQueue``. (``rid`` argument doesn't apply.) + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_QUEUE_FAMILY: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_QUEUE_FAMILY** = ``4`` + +The specific family the main queue belongs to. + +- Vulkan: the queue family index, an ``uint32_t``. (``rid`` argument doesn't apply.) + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_TEXTURE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_TEXTURE** = ``5`` + +- Vulkan: ``VkImage``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_TEXTURE_VIEW: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_TEXTURE_VIEW** = ``6`` + +The view of an owned or shared texture. + +- Vulkan: ``VkImageView``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_TEXTURE_DATA_FORMAT: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_TEXTURE_DATA_FORMAT** = ``7`` + +The native id of the data format of the texture. + +- Vulkan: ``VkFormat``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_SAMPLER: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_SAMPLER** = ``8`` + +- Vulkan: ``VkSampler``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_UNIFORM_SET: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_UNIFORM_SET** = ``9`` + +- Vulkan: ``VkDescriptorSet``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_BUFFER: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_BUFFER** = ``10`` + +Buffer of any kind of (storage, vertex, etc.). + +- Vulkan: ``VkBuffer``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_COMPUTE_PIPELINE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_COMPUTE_PIPELINE** = ``11`` + +- Vulkan: ``VkPipeline``. + +.. _class_RenderingDevice_constant_DRIVER_RESOURCE_RENDER_PIPELINE: + +.. rst-class:: classref-enumeration-constant + +:ref:`DriverResource` **DRIVER_RESOURCE_RENDER_PIPELINE** = ``12`` + +- Vulkan: ``VkPipeline``. + .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_DEVICE: .. rst-class:: classref-enumeration-constant :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_DEVICE** = ``0`` -Vulkan device driver resource. This is a "global" resource and ignores the RID passed in +*Deprecated.* Use :ref:`DRIVER_RESOURCE_LOGICAL_DEVICE`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_PHYSICAL_DEVICE: @@ -325,7 +447,7 @@ Vulkan device driver resource. This is a "global" resource and ignores the RID p :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_PHYSICAL_DEVICE** = ``1`` -Physical device (graphics card) driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_PHYSICAL_DEVICE`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_INSTANCE: @@ -333,7 +455,7 @@ Physical device (graphics card) driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_INSTANCE** = ``2`` -Vulkan instance driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_TOPMOST_OBJECT`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_QUEUE: @@ -341,7 +463,7 @@ Vulkan instance driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_QUEUE** = ``3`` -Vulkan queue driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_COMMAND_QUEUE`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_QUEUE_FAMILY_INDEX: @@ -349,7 +471,7 @@ Vulkan queue driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_QUEUE_FAMILY_INDEX** = ``4`` -Vulkan queue family index driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_QUEUE_FAMILY`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_IMAGE: @@ -357,7 +479,7 @@ Vulkan queue family index driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_IMAGE** = ``5`` -Vulkan image driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_TEXTURE`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_IMAGE_VIEW: @@ -365,7 +487,7 @@ Vulkan image driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_IMAGE_VIEW** = ``6`` -Vulkan image view driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_TEXTURE_VIEW`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_IMAGE_NATIVE_TEXTURE_FORMAT: @@ -373,7 +495,7 @@ Vulkan image view driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_IMAGE_NATIVE_TEXTURE_FORMAT** = ``7`` -Vulkan image native texture format driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_TEXTURE_DATA_FORMAT`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_SAMPLER: @@ -381,7 +503,7 @@ Vulkan image native texture format driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_SAMPLER** = ``8`` -Vulkan sampler driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_SAMPLER`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_DESCRIPTOR_SET: @@ -389,7 +511,7 @@ Vulkan sampler driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_DESCRIPTOR_SET** = ``9`` -Vulkan `descriptor set `__ driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_UNIFORM_SET`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_BUFFER: @@ -397,7 +519,7 @@ Vulkan `descriptor set `__ driv :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_BUFFER** = ``10`` -Vulkan buffer driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_BUFFER`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_COMPUTE_PIPELINE: @@ -405,7 +527,7 @@ Vulkan buffer driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_COMPUTE_PIPELINE** = ``11`` -Vulkan compute pipeline driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_COMPUTE_PIPELINE`. .. _class_RenderingDevice_constant_DRIVER_RESOURCE_VULKAN_RENDER_PIPELINE: @@ -413,7 +535,7 @@ Vulkan compute pipeline driver resource. :ref:`DriverResource` **DRIVER_RESOURCE_VULKAN_RENDER_PIPELINE** = ``12`` -Vulkan render pipeline driver resource. +*Deprecated.* Use :ref:`DRIVER_RESOURCE_RENDER_PIPELINE`. .. rst-class:: classref-item-separator @@ -3699,13 +3821,37 @@ flags **PipelineDynamicStateFlags**: enum **InitialAction**: +.. _class_RenderingDevice_constant_INITIAL_ACTION_LOAD: + +.. rst-class:: classref-enumeration-constant + +:ref:`InitialAction` **INITIAL_ACTION_LOAD** = ``0`` + +Load the previous contents of the framebuffer. + .. _class_RenderingDevice_constant_INITIAL_ACTION_CLEAR: .. rst-class:: classref-enumeration-constant -:ref:`InitialAction` **INITIAL_ACTION_CLEAR** = ``0`` +:ref:`InitialAction` **INITIAL_ACTION_CLEAR** = ``1`` + +Clear the whole framebuffer or its specified region. -Start rendering and clear the whole framebuffer. +.. _class_RenderingDevice_constant_INITIAL_ACTION_DISCARD: + +.. rst-class:: classref-enumeration-constant + +:ref:`InitialAction` **INITIAL_ACTION_DISCARD** = ``2`` + +Ignore the previous contents of the framebuffer. This is the fastest option if you'll overwrite all of the pixels and don't need to read any of them. + +.. _class_RenderingDevice_constant_INITIAL_ACTION_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`InitialAction` **INITIAL_ACTION_MAX** = ``3`` + +Represents the size of the :ref:`InitialAction` enum. .. _class_RenderingDevice_constant_INITIAL_ACTION_CLEAR_REGION: @@ -3713,47 +3859,39 @@ Start rendering and clear the whole framebuffer. :ref:`InitialAction` **INITIAL_ACTION_CLEAR_REGION** = ``1`` -Start rendering and clear the framebuffer in the specified region. +*Deprecated.* Use :ref:`INITIAL_ACTION_CLEAR` instead. .. _class_RenderingDevice_constant_INITIAL_ACTION_CLEAR_REGION_CONTINUE: .. rst-class:: classref-enumeration-constant -:ref:`InitialAction` **INITIAL_ACTION_CLEAR_REGION_CONTINUE** = ``2`` +:ref:`InitialAction` **INITIAL_ACTION_CLEAR_REGION_CONTINUE** = ``1`` -Continue rendering and clear the framebuffer in the specified region. Framebuffer must have been left in :ref:`FINAL_ACTION_CONTINUE` state as the final action previously. +*Deprecated.* Use :ref:`INITIAL_ACTION_LOAD` instead. .. _class_RenderingDevice_constant_INITIAL_ACTION_KEEP: .. rst-class:: classref-enumeration-constant -:ref:`InitialAction` **INITIAL_ACTION_KEEP** = ``3`` +:ref:`InitialAction` **INITIAL_ACTION_KEEP** = ``0`` -Start rendering, but keep attached color texture contents. If the framebuffer was previously used to read in a shader, this will automatically insert a layout transition. +*Deprecated.* Use :ref:`INITIAL_ACTION_LOAD` instead. .. _class_RenderingDevice_constant_INITIAL_ACTION_DROP: .. rst-class:: classref-enumeration-constant -:ref:`InitialAction` **INITIAL_ACTION_DROP** = ``4`` +:ref:`InitialAction` **INITIAL_ACTION_DROP** = ``2`` -Start rendering, ignore what is there; write above it. In general, this is the fastest option when you will be writing every single pixel and you don't need a clear color. +*Deprecated.* Use :ref:`INITIAL_ACTION_DISCARD` instead. .. _class_RenderingDevice_constant_INITIAL_ACTION_CONTINUE: .. rst-class:: classref-enumeration-constant -:ref:`InitialAction` **INITIAL_ACTION_CONTINUE** = ``5`` - -Continue rendering. Framebuffer must have been left in :ref:`FINAL_ACTION_CONTINUE` state as the final action previously. - -.. _class_RenderingDevice_constant_INITIAL_ACTION_MAX: - -.. rst-class:: classref-enumeration-constant - -:ref:`InitialAction` **INITIAL_ACTION_MAX** = ``6`` +:ref:`InitialAction` **INITIAL_ACTION_CONTINUE** = ``0`` -Represents the size of the :ref:`InitialAction` enum. +*Deprecated.* Use :ref:`INITIAL_ACTION_LOAD` instead. .. rst-class:: classref-item-separator @@ -3765,13 +3903,13 @@ Represents the size of the :ref:`InitialAction` **FINAL_ACTION_READ** = ``0`` +:ref:`FinalAction` **FINAL_ACTION_STORE** = ``0`` -Store the texture for reading and make it read-only if it has the :ref:`TEXTURE_USAGE_SAMPLING_BIT` bit (only applies to color, depth and stencil attachments). +Store the result of the draw list in the framebuffer. This is generally what you want to do. .. _class_RenderingDevice_constant_FINAL_ACTION_DISCARD: @@ -3779,23 +3917,31 @@ Store the texture for reading and make it read-only if it has the :ref:`TEXTURE_ :ref:`FinalAction` **FINAL_ACTION_DISCARD** = ``1`` -Discard the texture data and make it read-only if it has the :ref:`TEXTURE_USAGE_SAMPLING_BIT` bit (only applies to color, depth and stencil attachments). +Discard the contents of the framebuffer. This is the fastest option if you don't need to use the results of the draw list. -.. _class_RenderingDevice_constant_FINAL_ACTION_CONTINUE: +.. _class_RenderingDevice_constant_FINAL_ACTION_MAX: .. rst-class:: classref-enumeration-constant -:ref:`FinalAction` **FINAL_ACTION_CONTINUE** = ``2`` +:ref:`FinalAction` **FINAL_ACTION_MAX** = ``2`` -Store the texture and continue for further processing. Similar to :ref:`FINAL_ACTION_READ`, but does not make the texture read-only if it has the :ref:`TEXTURE_USAGE_SAMPLING_BIT` bit. +Represents the size of the :ref:`FinalAction` enum. -.. _class_RenderingDevice_constant_FINAL_ACTION_MAX: +.. _class_RenderingDevice_constant_FINAL_ACTION_READ: + +.. rst-class:: classref-enumeration-constant + +:ref:`FinalAction` **FINAL_ACTION_READ** = ``0`` + +*Deprecated.* Use :ref:`FINAL_ACTION_STORE` instead. + +.. _class_RenderingDevice_constant_FINAL_ACTION_CONTINUE: .. rst-class:: classref-enumeration-constant -:ref:`FinalAction` **FINAL_ACTION_MAX** = ``3`` +:ref:`FinalAction` **FINAL_ACTION_CONTINUE** = ``0`` -Represents the size of the :ref:`FinalAction` enum. +*Deprecated.* Use :ref:`FINAL_ACTION_STORE` instead. .. rst-class:: classref-item-separator @@ -4335,7 +4481,7 @@ Method Descriptions void **barrier** **(** |bitfield|\<:ref:`BarrierMask`\> from=32767, |bitfield|\<:ref:`BarrierMask`\> to=32767 **)** -Puts a memory barrier in place. This is used for synchronization to avoid data races. See also :ref:`full_barrier`, which may be useful for debugging. +*Deprecated.* Barriers are automatically inserted by RenderingDevice. .. rst-class:: classref-item-separator @@ -4345,9 +4491,9 @@ Puts a memory barrier in place. This is used for synchronization to avoid data r .. rst-class:: classref-method -:ref:`Error` **buffer_clear** **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +:ref:`Error` **buffer_clear** **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes **)** -Clears the contents of the ``buffer``, clearing ``size_bytes`` bytes, starting at ``offset``. Always raises a memory barrier. +Clears the contents of the ``buffer``, clearing ``size_bytes`` bytes, starting at ``offset``. Prints an error if: @@ -4363,6 +4509,26 @@ Prints an error if: ---- +.. _class_RenderingDevice_method_buffer_copy: + +.. rst-class:: classref-method + +:ref:`Error` **buffer_copy** **(** :ref:`RID` src_buffer, :ref:`RID` dst_buffer, :ref:`int` src_offset, :ref:`int` dst_offset, :ref:`int` size **)** + +Copies ``size`` bytes from the ``src_buffer`` at ``src_offset`` into ``dst_buffer`` at ``dst_offset``. + +Prints an error if: + +- ``size`` exceeds the size of either ``src_buffer`` or ``dst_buffer`` at their corresponding offsets + +- a draw list is currently active (created by :ref:`draw_list_begin`) + +- a compute list is currently active (created by :ref:`compute_list_begin`) + +.. rst-class:: classref-item-separator + +---- + .. _class_RenderingDevice_method_buffer_get_data: .. rst-class:: classref-method @@ -4379,9 +4545,9 @@ Returns a copy of the data of the specified ``buffer``, optionally ``offset_byte .. rst-class:: classref-method -:ref:`Error` **buffer_update** **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, :ref:`PackedByteArray` data, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +:ref:`Error` **buffer_update** **(** :ref:`RID` buffer, :ref:`int` offset, :ref:`int` size_bytes, :ref:`PackedByteArray` data **)** -Updates a region of ``size_bytes`` bytes, starting at ``offset``, in the buffer, with the specified ``data``. Raises a memory barrier except when ``post_barrier`` is set to :ref:`BARRIER_MASK_NO_BARRIER`. +Updates a region of ``size_bytes`` bytes, starting at ``offset``, in the buffer, with the specified ``data``. Prints an error if: @@ -4423,11 +4589,11 @@ Raises a Vulkan compute barrier in the specified ``compute_list``. .. rst-class:: classref-method -:ref:`int` **compute_list_begin** **(** :ref:`bool` allow_draw_overlap=false **)** +:ref:`int` **compute_list_begin** **(** **)** Starts a list of compute commands created with the ``compute_*`` methods. The returned value should be passed to other ``compute_list_*`` functions. -If ``allow_draw_overlap`` is ``true``, you may have one draw list running at the same time as one compute list. Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using :ref:`compute_list_end`. +Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using :ref:`compute_list_end`. A simple compute operation might look like this (code is not a complete example): @@ -4491,7 +4657,7 @@ Submits the compute list for processing on the GPU. This is the compute equivale .. rst-class:: classref-method -void **compute_list_end** **(** |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +void **compute_list_end** **(** **)** Finishes a list of compute commands created with the ``compute_*`` methods. @@ -4557,7 +4723,7 @@ void **draw_command_begin_label** **(** :ref:`String` name, :ref:` Create a command buffer debug label region that can be displayed in third-party tools such as `RenderDoc `__. All regions must be ended with a :ref:`draw_command_end_label` call. When viewed from the linear series of submissions to a single queue, calls to :ref:`draw_command_begin_label` and :ref:`draw_command_end_label` must be matched and balanced. -The ``VK_EXT_DEBUG_UTILS_EXTENSION_NAME`` Vulkan extension must be available and enabled for command buffer debug label region to work. See also :ref:`draw_command_insert_label` and :ref:`draw_command_end_label`. +The ``VK_EXT_DEBUG_UTILS_EXTENSION_NAME`` Vulkan extension must be available and enabled for command buffer debug label region to work. See also :ref:`draw_command_end_label`. .. rst-class:: classref-item-separator @@ -4581,7 +4747,7 @@ Ends the command buffer debug label region started by a :ref:`draw_command_begin void **draw_command_insert_label** **(** :ref:`String` name, :ref:`Color` color **)** -Inserts a command buffer debug label region in the current command buffer. Unlike :ref:`draw_command_begin_label`, this region should not be ended with a :ref:`draw_command_end_label` call. +*Deprecated.* Inserting labels no longer applies due to command reordering. .. rst-class:: classref-item-separator @@ -4591,7 +4757,7 @@ Inserts a command buffer debug label region in the current command buffer. Unlik .. rst-class:: classref-method -:ref:`int` **draw_list_begin** **(** :ref:`RID` framebuffer, :ref:`InitialAction` initial_color_action, :ref:`FinalAction` final_color_action, :ref:`InitialAction` initial_depth_action, :ref:`FinalAction` final_depth_action, :ref:`PackedColorArray` clear_color_values=PackedColorArray(), :ref:`float` clear_depth=1.0, :ref:`int` clear_stencil=0, :ref:`Rect2` region=Rect2(0, 0, 0, 0), :ref:`RID[]` storage_textures=[] **)** +:ref:`int` **draw_list_begin** **(** :ref:`RID` framebuffer, :ref:`InitialAction` initial_color_action, :ref:`FinalAction` final_color_action, :ref:`InitialAction` initial_depth_action, :ref:`FinalAction` final_depth_action, :ref:`PackedColorArray` clear_color_values=PackedColorArray(), :ref:`float` clear_depth=1.0, :ref:`int` clear_stencil=0, :ref:`Rect2` region=Rect2(0, 0, 0, 0) **)** Starts a list of raster drawing commands created with the ``draw_*`` methods. The returned value should be passed to other ``draw_list_*`` functions. @@ -4602,7 +4768,7 @@ A simple drawing operation might look like this (code is not a complete example) :: var rd = RenderingDevice.new() - var clear_colors = PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)] + var clear_colors = PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)]) var draw_list = rd.draw_list_begin(framebuffers[i], RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_READ, RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_DISCARD, clear_colors) # Draw opaque. @@ -4642,7 +4808,7 @@ High-level variant of :ref:`draw_list_begin` **draw_list_begin_split** **(** :ref:`RID` framebuffer, :ref:`int` splits, :ref:`InitialAction` initial_color_action, :ref:`FinalAction` final_color_action, :ref:`InitialAction` initial_depth_action, :ref:`FinalAction` final_depth_action, :ref:`PackedColorArray` clear_color_values=PackedColorArray(), :ref:`float` clear_depth=1.0, :ref:`int` clear_stencil=0, :ref:`Rect2` region=Rect2(0, 0, 0, 0), :ref:`RID[]` storage_textures=[] **)** -Variant of :ref:`draw_list_begin` with support for multiple splits. The ``splits`` parameter determines how many splits are created. +*Deprecated.* Split draw lists are used automatically by RenderingDevice. .. rst-class:: classref-item-separator @@ -4738,7 +4904,7 @@ Creates a scissor rectangle and enables it for the specified ``draw_list``. Scis .. rst-class:: classref-method -void **draw_list_end** **(** |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +void **draw_list_end** **(** **)** Finishes a list of raster drawing commands created with the ``draw_*`` methods. @@ -4776,7 +4942,7 @@ Sets the push constant data to ``buffer`` for the specified ``draw_list``. The s :ref:`int` **draw_list_switch_to_next_pass** **(** **)** -Switches to the next draw pass and returns the split's ID. Equivalent to :ref:`draw_list_switch_to_next_pass_split` with ``splits`` set to ``1``. +Switches to the next draw pass. .. rst-class:: classref-item-separator @@ -4788,7 +4954,7 @@ Switches to the next draw pass and returns the split's ID. Equivalent to :ref:`d :ref:`PackedInt64Array` **draw_list_switch_to_next_pass_split** **(** :ref:`int` splits **)** -Switches to the next draw pass, with the number of splits allocated specified in ``splits``. The return value is an array containing the ID of each split. For single-split usage, see :ref:`draw_list_switch_to_next_pass`. +*Deprecated.* Split draw lists are used automatically by RenderingDevice. .. rst-class:: classref-item-separator @@ -4928,7 +5094,7 @@ Tries to free an object in the RenderingDevice. To avoid memory leaks, this shou void **full_barrier** **(** **)** -Puts a *full* memory barrier in place. This is a memory :ref:`barrier` with all flags enabled. :ref:`full_barrier` it should only be used for debugging as it can severely impact performance. +*Deprecated.* Barriers are automatically inserted by RenderingDevice. .. rst-class:: classref-item-separator @@ -5360,7 +5526,7 @@ Once finished with your RID, you will want to free the RID using the RenderingDe .. rst-class:: classref-method -:ref:`Error` **texture_clear** **(** :ref:`RID` texture, :ref:`Color` color, :ref:`int` base_mipmap, :ref:`int` mipmap_count, :ref:`int` base_layer, :ref:`int` layer_count, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +:ref:`Error` **texture_clear** **(** :ref:`RID` texture, :ref:`Color` color, :ref:`int` base_mipmap, :ref:`int` mipmap_count, :ref:`int` base_layer, :ref:`int` layer_count **)** Clears the specified ``texture`` by replacing all of its pixels with the specified ``color``. ``base_mipmap`` and ``mipmap_count`` determine which mipmaps of the texture are affected by this clear operation, while ``base_layer`` and ``layer_count`` determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), ``base_layer`` must be ``0`` and ``layer_count`` must be ``1``. @@ -5374,7 +5540,7 @@ Clears the specified ``texture`` by replacing all of its pixels with the specifi .. rst-class:: classref-method -:ref:`Error` **texture_copy** **(** :ref:`RID` from_texture, :ref:`RID` to_texture, :ref:`Vector3` from_pos, :ref:`Vector3` to_pos, :ref:`Vector3` size, :ref:`int` src_mipmap, :ref:`int` dst_mipmap, :ref:`int` src_layer, :ref:`int` dst_layer, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +:ref:`Error` **texture_copy** **(** :ref:`RID` from_texture, :ref:`RID` to_texture, :ref:`Vector3` from_pos, :ref:`Vector3` to_pos, :ref:`Vector3` size, :ref:`int` src_mipmap, :ref:`int` dst_mipmap, :ref:`int` src_layer, :ref:`int` dst_layer **)** Copies the ``from_texture`` to ``to_texture`` with the specified ``from_pos``, ``to_pos`` and ``size`` coordinates. The Z axis of the ``from_pos``, ``to_pos`` and ``size`` must be ``0`` for 2-dimensional textures. Source and destination mipmaps/layers must also be specified, with these parameters being ``0`` for textures without mipmaps or single-layer textures. Returns :ref:`@GlobalScope.OK` if the texture copy was successful or :ref:`@GlobalScope.ERR_INVALID_PARAMETER` otherwise. @@ -5486,6 +5652,8 @@ Returns the internal graphics handle for this texture object. For use when commu \ **Note:** This function returns a ``uint64_t`` which internally maps to a ``GLuint`` (OpenGL) or ``VkImage`` (Vulkan). +\ *Deprecated.* Use :ref:`get_driver_resource` with :ref:`DRIVER_RESOURCE_TEXTURE` instead. + .. rst-class:: classref-item-separator ---- @@ -5530,7 +5698,7 @@ Returns ``true`` if the ``texture`` is valid, ``false`` otherwise. .. rst-class:: classref-method -:ref:`Error` **texture_resolve_multisample** **(** :ref:`RID` from_texture, :ref:`RID` to_texture, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +:ref:`Error` **texture_resolve_multisample** **(** :ref:`RID` from_texture, :ref:`RID` to_texture **)** Resolves the ``from_texture`` texture onto ``to_texture`` with multisample antialiasing enabled. This must be used when rendering a framebuffer for MSAA to work. Returns :ref:`@GlobalScope.OK` if successful, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` otherwise. @@ -5556,7 +5724,7 @@ Resolves the ``from_texture`` texture onto ``to_texture`` with multisample antia .. rst-class:: classref-method -:ref:`Error` **texture_update** **(** :ref:`RID` texture, :ref:`int` layer, :ref:`PackedByteArray` data, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** +:ref:`Error` **texture_update** **(** :ref:`RID` texture, :ref:`int` layer, :ref:`PackedByteArray` data **)** Updates texture data with new data, replacing the previous data in place. The updated texture data must have the same dimensions and format. For 2D textures (which only have one layer), ``layer`` must be ``0``. Returns :ref:`@GlobalScope.OK` if the update was successful, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` otherwise. diff --git a/classes/class_renderingserver.rst b/classes/class_renderingserver.rst index dbe725f0eb9..631c20ce334 100644 --- a/classes/class_renderingserver.rst +++ b/classes/class_renderingserver.rst @@ -267,6 +267,8 @@ Methods +----------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RenderingDevice` | :ref:`create_local_rendering_device` **(** **)** |const| | +----------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`debug_canvas_item_get_rect` **(** :ref:`RID` item **)** | + +----------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`decal_create` **(** **)** | +----------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`decal_set_albedo_mix` **(** :ref:`RID` decal, :ref:`float` albedo_mix **)** | @@ -3186,11 +3188,19 @@ Visible render pass (excluding shadows). Shadow render pass. Objects will be rendered several times depending on the number of amounts of lights with shadows and the number of directional shadow splits. +.. _class_RenderingServer_constant_VIEWPORT_RENDER_INFO_TYPE_CANVAS: + +.. rst-class:: classref-enumeration-constant + +:ref:`ViewportRenderInfoType` **VIEWPORT_RENDER_INFO_TYPE_CANVAS** = ``2`` + +Canvas item rendering. This includes all 2D rendering. + .. _class_RenderingServer_constant_VIEWPORT_RENDER_INFO_TYPE_MAX: .. rst-class:: classref-enumeration-constant -:ref:`ViewportRenderInfoType` **VIEWPORT_RENDER_INFO_TYPE_MAX** = ``2`` +:ref:`ViewportRenderInfoType` **VIEWPORT_RENDER_INFO_TYPE_MAX** = ``3`` Represents the size of the :ref:`ViewportRenderInfoType` enum. @@ -4630,7 +4640,7 @@ Uses the default filter mode for this :ref:`Viewport`. :ref:`CanvasItemTextureFilter` **CANVAS_ITEM_TEXTURE_FILTER_NEAREST** = ``1`` -The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_RenderingServer_constant_CANVAS_ITEM_TEXTURE_FILTER_LINEAR: @@ -4638,7 +4648,7 @@ The texture filter reads from the nearest pixel only. The simplest and fastest m :ref:`CanvasItemTextureFilter` **CANVAS_ITEM_TEXTURE_FILTER_LINEAR** = ``2`` -The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_RenderingServer_constant_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: @@ -4646,7 +4656,9 @@ The texture filter blends between the nearest 4 pixels. Use this when you want t :ref:`CanvasItemTextureFilter` **CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``3`` -The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_RenderingServer_constant_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: @@ -4654,7 +4666,9 @@ The texture filter reads from the nearest pixel in the nearest mipmap. The faste :ref:`CanvasItemTextureFilter` **CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``4`` -The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_RenderingServer_constant_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC: @@ -4662,7 +4676,9 @@ The texture filter blends between the nearest 4 pixels and between the nearest 2 :ref:`CanvasItemTextureFilter` **CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = ``5`` -The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. + +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS` is usually more appropriate in this case. .. _class_RenderingServer_constant_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC: @@ -4670,7 +4686,9 @@ The texture filter reads from the nearest pixel, but selects a mipmap based on t :ref:`CanvasItemTextureFilter` **CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = ``6`` -The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. + +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS` is usually more appropriate in this case. .. _class_RenderingServer_constant_CANVAS_ITEM_TEXTURE_FILTER_MAX: @@ -5224,7 +5242,7 @@ enum **Features**: :ref:`Features` **FEATURE_SHADERS** = ``0`` -Hardware supports shaders. This enum is currently unused in Godot 3.x. +*Deprecated.* This constant has not been used since Godot 3.0. .. _class_RenderingServer_constant_FEATURE_MULTITHREADED: @@ -5232,7 +5250,7 @@ Hardware supports shaders. This enum is currently unused in Godot 3.x. :ref:`Features` **FEATURE_MULTITHREADED** = ``1`` -Hardware supports multithreading. This enum is currently unused in Godot 3.x. +*Deprecated.* This constant has not been used since Godot 3.0. .. rst-class:: classref-section-separator @@ -6666,6 +6684,20 @@ Creates a RenderingDevice that can be used to do draw and compute operations on ---- +.. _class_RenderingServer_method_debug_canvas_item_get_rect: + +.. rst-class:: classref-method + +:ref:`Rect2` **debug_canvas_item_get_rect** **(** :ref:`RID` item **)** + +Returns the bounding rectangle for a canvas item in local space, as calculated by the renderer. This bound is used internally for culling. + +\ **Warning:** This function is intended for debugging in the editor, and will pass through and return a zero :ref:`Rect2` in exported projects. + +.. rst-class:: classref-item-separator + +---- + .. _class_RenderingServer_method_decal_create: .. rst-class:: classref-method @@ -7238,7 +7270,7 @@ Sets the size of the fog volume when shape is :ref:`FOG_VOLUME_SHAPE_ELLIPSOID` swap_buffers=true, :ref:`float` frame_step=0.0 **)** -Forces redrawing of all viewports at once. +Forces redrawing of all viewports at once. Must be called from the main thread. .. rst-class:: classref-item-separator @@ -7574,7 +7606,7 @@ Returns ``true`` if changes have been made to the RenderingServer's data. :ref:` :ref:`bool` **has_feature** **(** :ref:`Features` feature **)** |const| -Not yet implemented. Always returns ``false``. +*Deprecated.* This method has not been used since Godot 3.0. Always returns false. .. rst-class:: classref-item-separator @@ -10357,7 +10389,7 @@ Updates the texture specified by the ``texture`` :ref:`RID`'s data wi :ref:`Format` **texture_get_format** **(** :ref:`RID` texture **)** |const| -Returns the :ref:`Format` for the texture. +Returns the format for the texture. .. rst-class:: classref-item-separator diff --git a/classes/class_resource.rst b/classes/class_resource.rst index d0c4350eae1..b2667834390 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -21,10 +21,12 @@ Base class for serializable objects. Description ----------- -Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from :ref:`RefCounted`, resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. Once loaded from disk, further attempts to load a resource by :ref:`resource_path` returns the same reference. :ref:`PackedScene`, one of the most common :ref:`Object`\ s in a Godot project, is also a resource, uniquely capable of storing and instantiating the :ref:`Node`\ s it contains as many times as desired. +Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from :ref:`RefCounted`, resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. :ref:`PackedScene`, one of the most common :ref:`Object`\ s in a Godot project, is also a resource, uniquely capable of storing and instantiating the :ref:`Node`\ s it contains as many times as desired. In GDScript, resources can loaded from disk by their :ref:`resource_path` using :ref:`@GDScript.load` or :ref:`@GDScript.preload`. +The engine keeps a global cache of all loaded resources, referenced by paths (see :ref:`ResourceLoader.has_cached`). A resource will be cached when loaded for the first time and removed from cache once all references are released. When a resource is cached, subsequent loads using its path will return the cached reference. + \ **Note:** In C#, resources will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free resources that are no longer in use. This means that unused resources will linger on for a while before being removed. .. rst-class:: classref-introduction-group diff --git a/classes/class_resourceloader.rst b/classes/class_resourceloader.rst index 10f8ffba7e9..a5bcb388861 100644 --- a/classes/class_resourceloader.rst +++ b/classes/class_resourceloader.rst @@ -129,7 +129,7 @@ enum **CacheMode**: :ref:`CacheMode` **CACHE_MODE_IGNORE** = ``0`` - +The resource is always loaded from disk, even if a cache entry exists for its path, and the newly loaded copy will not be cached. Instances loaded with this mode will exist independently. .. _class_ResourceLoader_constant_CACHE_MODE_REUSE: @@ -137,7 +137,7 @@ enum **CacheMode**: :ref:`CacheMode` **CACHE_MODE_REUSE** = ``1`` - +If a resource is cached, returns the cached reference. Otherwise it's loaded from disk. .. _class_ResourceLoader_constant_CACHE_MODE_REPLACE: @@ -145,7 +145,7 @@ enum **CacheMode**: :ref:`CacheMode` **CACHE_MODE_REPLACE** = ``2`` - +The resource is always loaded from disk, even if a cache entry exists for its path. The cached entry will be replaced by the newly loaded copy. .. rst-class:: classref-section-separator @@ -180,6 +180,8 @@ Returns whether a recognized resource exists for the given ``path``. An optional ``type_hint`` can be used to further specify the :ref:`Resource` type that should be handled by the :ref:`ResourceFormatLoader`. Anything that inherits from :ref:`Resource` can be used as a type hint, for example :ref:`Image`. +\ **Note:** If you use :ref:`Resource.take_over_path`, this method will return ``true`` for the taken path even if the resource wasn't saved (i.e. exists only in resource cache). + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_richtexteffect.rst b/classes/class_richtexteffect.rst index 2d93807769e..0867182c83f 100644 --- a/classes/class_richtexteffect.rst +++ b/classes/class_richtexteffect.rst @@ -19,7 +19,7 @@ A custom effect for a :ref:`RichTextLabel`. Description ----------- -A custom effect for a :ref:`RichTextLabel`. +A custom effect for a :ref:`RichTextLabel`, which can be loaded in the :ref:`RichTextLabel` inspector or using :ref:`RichTextLabel.install_effect`. \ **Note:** For a **RichTextEffect** to be usable, a BBCode tag must be defined as a member variable called ``bbcode`` in the script. diff --git a/classes/class_richtextlabel.rst b/classes/class_richtextlabel.rst index 62c8b0cb537..f104ade88ba 100644 --- a/classes/class_richtextlabel.rst +++ b/classes/class_richtextlabel.rst @@ -1305,7 +1305,32 @@ Returns the number of visible paragraphs. A paragraph is considered visible if a void **install_effect** **(** :ref:`Variant` effect **)** -Installs a custom effect. ``effect`` should be a valid :ref:`RichTextEffect`. +Installs a custom effect. This can also be done in the RichTextLabel inspector using the :ref:`custom_effects` property. ``effect`` should be a valid :ref:`RichTextEffect`. + +Example RichTextEffect: + +:: + + # effect.gd + class_name MyCustomEffect + extends RichTextEffect + + var bbcode = "my_custom_effect" + + # ... + +Registering the above effect in RichTextLabel from script: + +:: + + # rich_text_label.gd + extends RichTextLabel + + func _ready(): + install_effect(MyCustomEffect.new()) + + # Alternatively, if not using `class_name` in the script that extends RichTextEffect: + install_effect(preload("res://effect.gd").new()) .. rst-class:: classref-item-separator diff --git a/classes/class_scenetree.rst b/classes/class_scenetree.rst index 7dcb7d56e0b..d155d61132f 100644 --- a/classes/class_scenetree.rst +++ b/classes/class_scenetree.rst @@ -93,6 +93,8 @@ Methods +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_node_count` **(** **)** |const| | +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_node_count_in_group` **(** :ref:`StringName` group **)** |const| | + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Node[]` | :ref:`get_nodes_in_group` **(** :ref:`StringName` group **)** | +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Tween[]` | :ref:`get_processed_tweens` **(** **)** | @@ -512,7 +514,7 @@ Changes the running scene to the one at the given ``path``, after loading it int Returns :ref:`@GlobalScope.OK` on success, :ref:`@GlobalScope.ERR_CANT_OPEN` if the ``path`` cannot be loaded into a :ref:`PackedScene`, or :ref:`@GlobalScope.ERR_CANT_CREATE` if that scene cannot be instantiated. -\ **Note:** The new scene node is added to the tree at the end of the frame. This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to :ref:`Node.queue_free`. As such, you won't be able to access the loaded scene immediately after the :ref:`change_scene_to_file` call. +\ **Note:** See :ref:`change_scene_to_packed` for details on the order of operations. .. rst-class:: classref-item-separator @@ -528,7 +530,13 @@ Changes the running scene to a new instance of the given :ref:`PackedScene` on success, :ref:`@GlobalScope.ERR_CANT_CREATE` if the scene cannot be instantiated, or :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if the scene is invalid. -\ **Note:** The new scene node is added to the tree at the end of the frame. You won't be able to access it immediately after the :ref:`change_scene_to_packed` call. +\ **Note:** Operations happen in the following order when :ref:`change_scene_to_packed` is called: + +1. The current scene node is immediately removed from the tree. From that point, :ref:`Node.get_tree` called on the current (outgoing) scene will return ``null``. :ref:`current_scene` will be ``null``, too, because the new scene is not available yet. + +2. At the end of the frame, the formerly current scene, already removed from the tree, will be deleted (freed from memory) and then the new scene will be instantiated and added to the tree. :ref:`Node.get_tree` and :ref:`current_scene` will be back to working as usual. + +This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to :ref:`Node.queue_free`. .. rst-class:: classref-item-separator @@ -641,6 +649,18 @@ Returns the number of nodes in this **SceneTree**. ---- +.. _class_SceneTree_method_get_node_count_in_group: + +.. rst-class:: classref-method + +:ref:`int` **get_node_count_in_group** **(** :ref:`StringName` group **)** |const| + +Returns the number of nodes assigned to the given group. + +.. rst-class:: classref-item-separator + +---- + .. _class_SceneTree_method_get_nodes_in_group: .. rst-class:: classref-method diff --git a/classes/class_script.rst b/classes/class_script.rst index bfb139f48cf..06b399e7515 100644 --- a/classes/class_script.rst +++ b/classes/class_script.rst @@ -59,6 +59,8 @@ Methods +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Script` | :ref:`get_base_script` **(** **)** |const| | +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_global_name` **(** **)** |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`get_instance_base_type` **(** **)** |const| | +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_property_default_value` **(** :ref:`StringName` property **)** | @@ -135,6 +137,39 @@ Returns ``true`` if the script can be instantiated. Returns the script directly inherited by this script. +.. rst-class:: classref-item-separator + +---- + +.. _class_Script_method_get_global_name: + +.. rst-class:: classref-method + +:ref:`StringName` **get_global_name** **(** **)** |const| + +Returns the class name associated with the script, if there is one. Returns an empty string otherwise. + +To give the script a global name, you can use the ``class_name`` keyword in GDScript and the ``[GlobalClass]`` attribute in C#. + + +.. tabs:: + + .. code-tab:: gdscript + + class_name MyNode + extends Node + + .. code-tab:: csharp + + using Godot; + + [GlobalClass] + public partial class MyNode : Node + { + } + + + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_scriptlanguageextension.rst b/classes/class_scriptlanguageextension.rst index 3b7cdd84e61..e27a6d3ef62 100644 --- a/classes/class_scriptlanguageextension.rst +++ b/classes/class_scriptlanguageextension.rst @@ -57,7 +57,7 @@ Methods +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`_debug_parse_stack_level_expression` **(** :ref:`int` level, :ref:`String` expression, :ref:`int` max_subitems, :ref:`int` max_depth **)** |virtual| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`_find_function` **(** :ref:`String` class_name, :ref:`String` function_name **)** |virtual| |const| | + | :ref:`int` | :ref:`_find_function` **(** :ref:`String` function, :ref:`String` code **)** |virtual| |const| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_finish` **(** **)** |virtual| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -113,6 +113,8 @@ Methods +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`_profiling_get_frame_data` **(** ScriptLanguageExtensionProfilingInfo* info_array, :ref:`int` info_max **)** |virtual| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`_profiling_set_save_native_calls` **(** :ref:`bool` enable **)** |virtual| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_profiling_start` **(** **)** |virtual| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_profiling_stop` **(** **)** |virtual| | @@ -608,11 +610,9 @@ void* **_debug_get_stack_level_instance** **(** :ref:`int` level **)* .. rst-class:: classref-method -:ref:`int` **_find_function** **(** :ref:`String` class_name, :ref:`String` function_name **)** |virtual| |const| - -.. container:: contribute +:ref:`int` **_find_function** **(** :ref:`String` function, :ref:`String` code **)** |virtual| |const| - There is currently no description for this method. Please help us by :ref:`contributing one `! +Returns the line where the function is defined in the code, or ``-1`` if the function is not present. .. rst-class:: classref-item-separator @@ -994,6 +994,20 @@ void **_init** **(** **)** |virtual| ---- +.. _class_ScriptLanguageExtension_private_method__profiling_set_save_native_calls: + +.. rst-class:: classref-method + +void **_profiling_set_save_native_calls** **(** :ref:`bool` enable **)** |virtual| + +.. container:: contribute + + There is currently no description for this method. Please help us by :ref:`contributing one `! + +.. rst-class:: classref-item-separator + +---- + .. _class_ScriptLanguageExtension_private_method__profiling_start: .. rst-class:: classref-method diff --git a/classes/class_skeleton3d.rst b/classes/class_skeleton3d.rst index 0b49aa2bbaa..413ba613242 100644 --- a/classes/class_skeleton3d.rst +++ b/classes/class_skeleton3d.rst @@ -25,8 +25,6 @@ The overall transform of a bone with respect to the skeleton is determined by bo Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it is not the actual global/world transform of the bone. -To setup different types of inverse kinematics, consider using :ref:`SkeletonIK3D`, or add a custom IK implementation in :ref:`Node._process` as a child node. - .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_slider.rst b/classes/class_slider.rst index 883712716da..efc975a233c 100644 --- a/classes/class_slider.rst +++ b/classes/class_slider.rst @@ -100,7 +100,7 @@ Emitted when dragging stops. If ``value_changed`` is true, :ref:`Range.value` signal. .. rst-class:: classref-section-separator diff --git a/classes/class_sprite2d.rst b/classes/class_sprite2d.rst index 51bced63328..6b3d53a8f60 100644 --- a/classes/class_sprite2d.rst +++ b/classes/class_sprite2d.rst @@ -176,7 +176,7 @@ If ``true``, texture is flipped vertically. - void **set_frame** **(** :ref:`int` value **)** - :ref:`int` **get_frame** **(** **)** -Current frame to display from sprite sheet. :ref:`hframes` or :ref:`vframes` must be greater than 1. +Current frame to display from sprite sheet. :ref:`hframes` or :ref:`vframes` must be greater than 1. This property is automatically adjusted when :ref:`hframes` or :ref:`vframes` are changed to keep pointing to the same visual frame (same column and row). If that's impossible, this value is reset to ``0``. .. rst-class:: classref-item-separator @@ -210,7 +210,7 @@ Coordinates of the frame to display from sprite sheet. This is as an alias for t - void **set_hframes** **(** :ref:`int` value **)** - :ref:`int` **get_hframes** **(** **)** -The number of columns in the sprite sheet. +The number of columns in the sprite sheet. When this property is changed, :ref:`frame` is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, :ref:`frame` is reset to ``0``. .. rst-class:: classref-item-separator @@ -312,7 +312,7 @@ The region of the atlas texture to display. :ref:`region_enabled` value **)** - :ref:`int` **get_vframes** **(** **)** -The number of rows in the sprite sheet. +The number of rows in the sprite sheet. When this property is changed, :ref:`frame` is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, :ref:`frame` is reset to ``0``. .. rst-class:: classref-section-separator diff --git a/classes/class_sprite3d.rst b/classes/class_sprite3d.rst index 42adf56d105..1acb2f0cff0 100644 --- a/classes/class_sprite3d.rst +++ b/classes/class_sprite3d.rst @@ -94,7 +94,7 @@ Property Descriptions - void **set_frame** **(** :ref:`int` value **)** - :ref:`int` **get_frame** **(** **)** -Current frame to display from sprite sheet. :ref:`hframes` or :ref:`vframes` must be greater than 1. +Current frame to display from sprite sheet. :ref:`hframes` or :ref:`vframes` must be greater than 1. This property is automatically adjusted when :ref:`hframes` or :ref:`vframes` are changed to keep pointing to the same visual frame (same column and row). If that's impossible, this value is reset to ``0``. .. rst-class:: classref-item-separator @@ -128,7 +128,7 @@ Coordinates of the frame to display from sprite sheet. This is as an alias for t - void **set_hframes** **(** :ref:`int` value **)** - :ref:`int` **get_hframes** **(** **)** -The number of columns in the sprite sheet. +The number of columns in the sprite sheet. When this property is changed, :ref:`frame` is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, :ref:`frame` is reset to ``0``. .. rst-class:: classref-item-separator @@ -196,7 +196,7 @@ The region of the atlas texture to display. :ref:`region_enabled` value **)** - :ref:`int` **get_vframes** **(** **)** -The number of rows in the sprite sheet. +The number of rows in the sprite sheet. When this property is changed, :ref:`frame` is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, :ref:`frame` is reset to ``0``. .. |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_string.rst b/classes/class_string.rst index 15a10337844..7d91b325238 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -458,16 +458,16 @@ Changes the appearance of the string: replaces underscores (``_``) with spaces, "move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path" + "2D, FPS, PNG".capitalize() # Returns "2d, Fps, Png" .. code-tab:: csharp "move_local_x".Capitalize(); // Returns "Move Local X" "sceneFile_path".Capitalize(); // Returns "Scene File Path" + "2D, FPS, PNG".Capitalize(); // Returns "2d, Fps, Png" -\ **Note:** This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms (``"2D"``, ``"FPS"``, ``"PNG"``, etc.) as you may expect. - .. rst-class:: classref-item-separator ---- @@ -803,7 +803,7 @@ This is faster than :ref:`split`, if you only need on Returns the 32-bit hash value representing the string's contents. -\ **Note:** Strings with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different. +\ **Note:** Strings with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the contrary, strings with different hash values are guaranteed to be different. .. rst-class:: classref-item-separator @@ -1833,7 +1833,7 @@ Converts the string representing an integer number into an :ref:`int` :ref:`String` **to_lower** **(** **)** |const| -Returns the string converted to lowercase. +Returns the string converted to ``lowercase``. .. rst-class:: classref-item-separator @@ -1859,6 +1859,25 @@ Returns the string converted to ``PascalCase``. Returns the string converted to ``snake_case``. +\ **Note:** Numbers followed by a *single* letter are not separated in the conversion to keep some words (such as "2D") together. + + +.. tabs:: + + .. code-tab:: gdscript + + "Node2D".to_snake_case() # Returns "node_2d" + "2nd place".to_snake_case() # Returns "2_nd_place" + "Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder" + + .. code-tab:: csharp + + "Node2D".ToSnakeCase(); // Returns "node_2d" + "2nd place".ToSnakeCase(); // Returns "2_nd_place" + "Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder" + + + .. rst-class:: classref-item-separator ---- @@ -1869,7 +1888,7 @@ Returns the string converted to ``snake_case``. :ref:`String` **to_upper** **(** **)** |const| -Returns the string converted to uppercase. +Returns the string converted to ``UPPERCASE``. .. rst-class:: classref-item-separator diff --git a/classes/class_stringname.rst b/classes/class_stringname.rst index 78f95eaec21..bcebd2ac23c 100644 --- a/classes/class_stringname.rst +++ b/classes/class_stringname.rst @@ -25,8 +25,14 @@ See also :ref:`NodePath`, which is a similar concept specificall All of :ref:`String`'s methods are available in this class too. They convert the **StringName** into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired. +\ **Note:** In C#, an explicit conversion to ``System.String`` is required to use the methods listed on this page. Use the ``ToString()`` method to cast a **StringName** to a string, and then use the equivalent methods in ``System.String`` or ``StringExtensions``. + \ **Note:** In a boolean context, a **StringName** will evaluate to ``false`` if it is empty (``StringName("")``). Otherwise, a **StringName** will always evaluate to ``true``. The ``not`` operator cannot be used. Instead, :ref:`is_empty` should be used to check for empty **StringName**\ s. +.. note:: + + There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. + .. rst-class:: classref-reftable-group Constructors @@ -425,16 +431,16 @@ Changes the appearance of the string: replaces underscores (``_``) with spaces, "move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path" + "2D, FPS, PNG".capitalize() # Returns "2d, Fps, Png" .. code-tab:: csharp "move_local_x".Capitalize(); // Returns "Move Local X" "sceneFile_path".Capitalize(); // Returns "Scene File Path" + "2D, FPS, PNG".Capitalize(); // Returns "2d, Fps, Png" -\ **Note:** This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms (``"2D"``, ``"FPS"``, ``"PNG"``, etc.) as you may expect. - .. rst-class:: classref-item-separator ---- @@ -753,7 +759,7 @@ This is faster than :ref:`split`, if you only nee Returns the 32-bit hash value representing the string's contents. -\ **Note:** Strings with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different. +\ **Note:** Strings with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the contrary, strings with different hash values are guaranteed to be different. .. rst-class:: classref-item-separator @@ -1672,7 +1678,7 @@ Converts the string representing an integer number into an :ref:`int` :ref:`String` **to_lower** **(** **)** |const| -Returns the string converted to lowercase. +Returns the string converted to ``lowercase``. .. rst-class:: classref-item-separator @@ -1698,6 +1704,25 @@ Returns the string converted to ``PascalCase``. Returns the string converted to ``snake_case``. +\ **Note:** Numbers followed by a *single* letter are not separated in the conversion to keep some words (such as "2D") together. + + +.. tabs:: + + .. code-tab:: gdscript + + "Node2D".to_snake_case() # Returns "node_2d" + "2nd place".to_snake_case() # Returns "2_nd_place" + "Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder" + + .. code-tab:: csharp + + "Node2D".ToSnakeCase(); // Returns "node_2d" + "2nd place".ToSnakeCase(); // Returns "2_nd_place" + "Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder" + + + .. rst-class:: classref-item-separator ---- @@ -1708,7 +1733,7 @@ Returns the string converted to ``snake_case``. :ref:`String` **to_upper** **(** **)** |const| -Returns the string converted to uppercase. +Returns the string converted to ``UPPERCASE``. .. rst-class:: classref-item-separator diff --git a/classes/class_tabcontainer.rst b/classes/class_tabcontainer.rst index 7265cd9fe47..315f18144f9 100644 --- a/classes/class_tabcontainer.rst +++ b/classes/class_tabcontainer.rst @@ -38,25 +38,27 @@ Properties .. table:: :widths: auto - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`all_tabs_in_front` | ``false`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`clip_tabs` | ``true`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`int` | :ref:`current_tab` | ``0`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`drag_to_rearrange_enabled` | ``false`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`AlignmentMode` | :ref:`tab_alignment` | ``0`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`FocusMode` | :ref:`tab_focus_mode` | ``2`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`int` | :ref:`tabs_rearrange_group` | ``-1`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`tabs_visible` | ``true`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`use_hidden_tabs_for_min_size` | ``false`` | - +-------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`all_tabs_in_front` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`clip_tabs` | ``true`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`current_tab` | ``0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`drag_to_rearrange_enabled` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`AlignmentMode` | :ref:`tab_alignment` | ``0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`FocusMode` | :ref:`tab_focus_mode` | ``2`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`TabPosition` | :ref:`tabs_position` | ``0`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`tabs_rearrange_group` | ``-1`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`tabs_visible` | ``true`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`use_hidden_tabs_for_min_size` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group @@ -271,6 +273,45 @@ Emitted when a tab is selected via click, directional input, or script, even if .. rst-class:: classref-descriptions-group +Enumerations +------------ + +.. _enum_TabContainer_TabPosition: + +.. rst-class:: classref-enumeration + +enum **TabPosition**: + +.. _class_TabContainer_constant_POSITION_TOP: + +.. rst-class:: classref-enumeration-constant + +:ref:`TabPosition` **POSITION_TOP** = ``0`` + +Places the tab bar at the top. + +.. _class_TabContainer_constant_POSITION_BOTTOM: + +.. rst-class:: classref-enumeration-constant + +:ref:`TabPosition` **POSITION_BOTTOM** = ``1`` + +Places the tab bar at the bottom. The tab bar's :ref:`StyleBox` will be flipped vertically. + +.. _class_TabContainer_constant_POSITION_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`TabPosition` **POSITION_MAX** = ``2`` + +Represents the size of the :ref:`TabPosition` enum. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Property Descriptions --------------------- @@ -376,6 +417,23 @@ The focus access mode for the internal :ref:`TabBar` node. ---- +.. _class_TabContainer_property_tabs_position: + +.. rst-class:: classref-property + +:ref:`TabPosition` **tabs_position** = ``0`` + +.. rst-class:: classref-property-setget + +- void **set_tabs_position** **(** :ref:`TabPosition` value **)** +- :ref:`TabPosition` **get_tabs_position** **(** **)** + +Sets the position of the tab bar. See :ref:`TabPosition` for details. + +.. rst-class:: classref-item-separator + +---- + .. _class_TabContainer_property_tabs_rearrange_group: .. rst-class:: classref-property diff --git a/classes/class_textline.rst b/classes/class_textline.rst index f9c7092a718..0f69e797601 100644 --- a/classes/class_textline.rst +++ b/classes/class_textline.rst @@ -34,6 +34,8 @@ Properties +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+ | :ref:`Direction` | :ref:`direction` | ``0`` | +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`ellipsis_char` | ``"…"`` | + +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+ | |bitfield|\<:ref:`JustificationFlag`\> | :ref:`flags` | ``3`` | +---------------------------------------------------------------------------+-----------------------------------------------------------------------------+-----------+ | :ref:`Orientation` | :ref:`orientation` | ``0`` | @@ -136,6 +138,23 @@ Text writing direction. ---- +.. _class_TextLine_property_ellipsis_char: + +.. rst-class:: classref-property + +:ref:`String` **ellipsis_char** = ``"…"`` + +.. rst-class:: classref-property-setget + +- void **set_ellipsis_char** **(** :ref:`String` value **)** +- :ref:`String` **get_ellipsis_char** **(** **)** + +Ellipsis character used for text clipping. + +.. rst-class:: classref-item-separator + +---- + .. _class_TextLine_property_flags: .. rst-class:: classref-property diff --git a/classes/class_textparagraph.rst b/classes/class_textparagraph.rst index a549c5f1cf3..20f8d6ddb5d 100644 --- a/classes/class_textparagraph.rst +++ b/classes/class_textparagraph.rst @@ -38,6 +38,8 @@ Properties +---------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------+ | :ref:`Direction` | :ref:`direction` | ``0`` | +---------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`ellipsis_char` | ``"…"`` | + +---------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------+ | |bitfield|\<:ref:`JustificationFlag`\> | :ref:`justification_flags` | ``163`` | +---------------------------------------------------------------------------+----------------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`max_lines_visible` | ``-1`` | @@ -204,6 +206,23 @@ Text writing direction. ---- +.. _class_TextParagraph_property_ellipsis_char: + +.. rst-class:: classref-property + +:ref:`String` **ellipsis_char** = ``"…"`` + +.. rst-class:: classref-property-setget + +- void **set_ellipsis_char** **(** :ref:`String` value **)** +- :ref:`String` **get_ellipsis_char** **(** **)** + +Ellipsis character used for text clipping. + +.. rst-class:: classref-item-separator + +---- + .. _class_TextParagraph_property_justification_flags: .. rst-class:: classref-property diff --git a/classes/class_textserver.rst b/classes/class_textserver.rst index 0ed6f5ef17e..d8a92e49dcd 100644 --- a/classes/class_textserver.rst +++ b/classes/class_textserver.rst @@ -326,6 +326,8 @@ Methods +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedInt32Array` | :ref:`shaped_text_get_character_breaks` **(** :ref:`RID` shaped **)** |const| | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shaped_text_get_custom_ellipsis` **(** :ref:`RID` shaped **)** |const| | + +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`shaped_text_get_custom_punctuation` **(** :ref:`RID` shaped **)** |const| | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`shaped_text_get_descent` **(** :ref:`RID` shaped **)** |const| | @@ -404,6 +406,8 @@ Methods +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`shaped_text_set_bidi_override` **(** :ref:`RID` shaped, :ref:`Array` override **)** | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`shaped_text_set_custom_ellipsis` **(** :ref:`RID` shaped, :ref:`int` char **)** | + +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`shaped_text_set_custom_punctuation` **(** :ref:`RID` shaped, :ref:`String` punct **)** | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`shaped_text_set_direction` **(** :ref:`RID` shaped, :ref:`Direction` direction=0 **)** | @@ -538,7 +542,7 @@ Vertical BGR subpixel layout. :ref:`FontLCDSubpixelLayout` **FONT_LCD_SUBPIXEL_LAYOUT_MAX** = ``5`` - +Represents the size of the :ref:`FontLCDSubpixelLayout` enum. .. rst-class:: classref-item-separator @@ -948,7 +952,7 @@ Determines whether the ellipsis at the end of the text is enforced and may not b :ref:`TextOverrunFlag` **OVERRUN_JUSTIFICATION_AWARE** = ``16`` - +Accounts for the text being justified before attempting to trim it (see :ref:`JustificationFlag`). .. rst-class:: classref-item-separator @@ -1376,7 +1380,7 @@ Spacing at the bottom of the line. :ref:`SpacingType` **SPACING_MAX** = ``4`` - +Represents the size of the :ref:`SpacingType` enum. .. rst-class:: classref-item-separator @@ -3359,6 +3363,18 @@ Returns array of the composite character boundaries. ---- +.. _class_TextServer_method_shaped_text_get_custom_ellipsis: + +.. rst-class:: classref-method + +:ref:`int` **shaped_text_get_custom_ellipsis** **(** :ref:`RID` shaped **)** |const| + +Returns ellipsis character used for text clipping. + +.. rst-class:: classref-item-separator + +---- + .. _class_TextServer_method_shaped_text_get_custom_punctuation: .. rst-class:: classref-method @@ -3833,6 +3849,18 @@ Override ranges should cover full source text without overlaps. BiDi algorithm w ---- +.. _class_TextServer_method_shaped_text_set_custom_ellipsis: + +.. rst-class:: classref-method + +void **shaped_text_set_custom_ellipsis** **(** :ref:`RID` shaped, :ref:`int` char **)** + +Sets ellipsis character used for text clipping. + +.. rst-class:: classref-item-separator + +---- + .. _class_TextServer_method_shaped_text_set_custom_punctuation: .. rst-class:: classref-method diff --git a/classes/class_textserverextension.rst b/classes/class_textserverextension.rst index c83473dee3d..5eb1e35f4d0 100644 --- a/classes/class_textserverextension.rst +++ b/classes/class_textserverextension.rst @@ -330,6 +330,8 @@ Methods +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedInt32Array` | :ref:`_shaped_text_get_character_breaks` **(** :ref:`RID` shaped **)** |virtual| |const| | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_shaped_text_get_custom_ellipsis` **(** :ref:`RID` shaped **)** |virtual| |const| | + +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`_shaped_text_get_custom_punctuation` **(** :ref:`RID` shaped **)** |virtual| |const| | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`_shaped_text_get_descent` **(** :ref:`RID` shaped **)** |virtual| |const| | @@ -406,6 +408,8 @@ Methods +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_shaped_text_set_bidi_override` **(** :ref:`RID` shaped, :ref:`Array` override **)** |virtual| | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`_shaped_text_set_custom_ellipsis` **(** :ref:`RID` shaped, :ref:`int` char **)** |virtual| | + +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_shaped_text_set_custom_punctuation` **(** :ref:`RID` shaped, :ref:`String` punct **)** |virtual| | +-----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_shaped_text_set_direction` **(** :ref:`RID` shaped, :ref:`Direction` direction **)** |virtual| | @@ -2540,6 +2544,20 @@ void **_shaped_text_get_carets** **(** :ref:`RID` shaped, :ref:`int` **_shaped_text_get_custom_ellipsis** **(** :ref:`RID` shaped **)** |virtual| |const| + +.. container:: contribute + + There is currently no description for this method. Please help us by :ref:`contributing one `! + +.. rst-class:: classref-item-separator + +---- + .. _class_TextServerExtension_private_method__shaped_text_get_custom_punctuation: .. rst-class:: classref-method @@ -3072,6 +3090,20 @@ void **_shaped_text_set_bidi_override** **(** :ref:`RID` shaped, :ref ---- +.. _class_TextServerExtension_private_method__shaped_text_set_custom_ellipsis: + +.. rst-class:: classref-method + +void **_shaped_text_set_custom_ellipsis** **(** :ref:`RID` shaped, :ref:`int` char **)** |virtual| + +.. container:: contribute + + There is currently no description for this method. Please help us by :ref:`contributing one `! + +.. rst-class:: classref-item-separator + +---- + .. _class_TextServerExtension_private_method__shaped_text_set_custom_punctuation: .. rst-class:: classref-method diff --git a/classes/class_texture2d.rst b/classes/class_texture2d.rst index 46787e5a7c5..146f0829271 100644 --- a/classes/class_texture2d.rst +++ b/classes/class_texture2d.rst @@ -238,6 +238,8 @@ Returns the texture height in pixels. Returns an :ref:`Image` that is a copy of data from this **Texture2D** (a new :ref:`Image` is created each time). :ref:`Image`\ s can be accessed and manipulated directly. +\ **Note:** This will return ``null`` if this **Texture2D** is invalid. + \ **Note:** This will fetch the texture data from the GPU, which might cause performance problems when overused. .. rst-class:: classref-item-separator diff --git a/classes/class_textureprogressbar.rst b/classes/class_textureprogressbar.rst index d8ab21094c1..63b4445b419 100644 --- a/classes/class_textureprogressbar.rst +++ b/classes/class_textureprogressbar.rst @@ -224,7 +224,7 @@ If ``true``, Godot treats the bar's textures like in :ref:`NinePatchRect` value **)** - :ref:`Vector2` **get_radial_center_offset** **(** **)** -Offsets :ref:`texture_progress` if :ref:`fill_mode` is :ref:`FILL_CLOCKWISE` or :ref:`FILL_COUNTER_CLOCKWISE`. +Offsets :ref:`texture_progress` if :ref:`fill_mode` is :ref:`FILL_CLOCKWISE`, :ref:`FILL_COUNTER_CLOCKWISE`, or :ref:`FILL_CLOCKWISE_AND_COUNTER_CLOCKWISE`. .. rst-class:: classref-item-separator @@ -241,7 +241,7 @@ Offsets :ref:`texture_progress` value **)** - :ref:`float` **get_fill_degrees** **(** **)** -Upper limit for the fill of :ref:`texture_progress` if :ref:`fill_mode` is :ref:`FILL_CLOCKWISE` or :ref:`FILL_COUNTER_CLOCKWISE`. When the node's ``value`` is equal to its ``max_value``, the texture fills up to this angle. +Upper limit for the fill of :ref:`texture_progress` if :ref:`fill_mode` is :ref:`FILL_CLOCKWISE`, :ref:`FILL_COUNTER_CLOCKWISE`, or :ref:`FILL_CLOCKWISE_AND_COUNTER_CLOCKWISE`. When the node's ``value`` is equal to its ``max_value``, the texture fills up to this angle. See :ref:`Range.value`, :ref:`Range.max_value`. @@ -260,7 +260,7 @@ See :ref:`Range.value`, :ref:`Range.max_value` value **)** - :ref:`float` **get_radial_initial_angle** **(** **)** -Starting angle for the fill of :ref:`texture_progress` if :ref:`fill_mode` is :ref:`FILL_CLOCKWISE` or :ref:`FILL_COUNTER_CLOCKWISE`. When the node's ``value`` is equal to its ``min_value``, the texture doesn't show up at all. When the ``value`` increases, the texture fills and tends towards :ref:`radial_fill_degrees`. +Starting angle for the fill of :ref:`texture_progress` if :ref:`fill_mode` is :ref:`FILL_CLOCKWISE`, :ref:`FILL_COUNTER_CLOCKWISE`, or :ref:`FILL_CLOCKWISE_AND_COUNTER_CLOCKWISE`. When the node's ``value`` is equal to its ``min_value``, the texture doesn't show up at all. When the ``value`` increases, the texture fills and tends towards :ref:`radial_fill_degrees`. .. rst-class:: classref-item-separator @@ -277,7 +277,7 @@ Starting angle for the fill of :ref:`texture_progress` margin, :ref:`int` value **)** - :ref:`int` **get_stretch_margin** **(** :ref:`Side` margin **)** |const| -The height of the 9-patch's bottom row. A margin of 16 means the 9-slice's bottom corners and side will have a height of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. +The height of the 9-patch's bottom row. A margin of 16 means the 9-slice's bottom corners and side will have a height of 16 pixels. You can set all 4 margin values individually to create panels with non-uniform borders. Only effective if :ref:`nine_patch_stretch` is ``true``. .. rst-class:: classref-item-separator @@ -294,7 +294,7 @@ The height of the 9-patch's bottom row. A margin of 16 means the 9-slice's botto - void **set_stretch_margin** **(** :ref:`Side` margin, :ref:`int` value **)** - :ref:`int` **get_stretch_margin** **(** :ref:`Side` margin **)** |const| -The width of the 9-patch's left column. +The width of the 9-patch's left column. Only effective if :ref:`nine_patch_stretch` is ``true``. .. rst-class:: classref-item-separator @@ -311,7 +311,7 @@ The width of the 9-patch's left column. - void **set_stretch_margin** **(** :ref:`Side` margin, :ref:`int` value **)** - :ref:`int` **get_stretch_margin** **(** :ref:`Side` margin **)** |const| -The width of the 9-patch's right column. +The width of the 9-patch's right column. Only effective if :ref:`nine_patch_stretch` is ``true``. .. rst-class:: classref-item-separator @@ -328,7 +328,7 @@ The width of the 9-patch's right column. - void **set_stretch_margin** **(** :ref:`Side` margin, :ref:`int` value **)** - :ref:`int` **get_stretch_margin** **(** :ref:`Side` margin **)** |const| -The height of the 9-patch's top row. +The height of the 9-patch's top row. Only effective if :ref:`nine_patch_stretch` is ``true``. .. rst-class:: classref-item-separator diff --git a/classes/class_tiledata.rst b/classes/class_tiledata.rst index db8f6c0bb52..ef421bc9f7d 100644 --- a/classes/class_tiledata.rst +++ b/classes/class_tiledata.rst @@ -61,55 +61,55 @@ Methods .. table:: :widths: auto - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`add_collision_polygon` **(** :ref:`int` layer_id **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_collision_polygon_one_way_margin` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector2Array` | :ref:`get_collision_polygon_points` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_collision_polygons_count` **(** :ref:`int` layer_id **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_constant_angular_velocity` **(** :ref:`int` layer_id **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`get_constant_linear_velocity` **(** :ref:`int` layer_id **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`get_custom_data` **(** :ref:`String` layer_name **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`get_custom_data_by_layer_id` **(** :ref:`int` layer_id **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`NavigationPolygon` | :ref:`get_navigation_polygon` **(** :ref:`int` layer_id **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`OccluderPolygon2D` | :ref:`get_occluder` **(** :ref:`int` layer_id **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_terrain_peering_bit` **(** :ref:`CellNeighbor` peering_bit **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_collision_polygon_one_way` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** |const| | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`remove_collision_polygon` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_collision_polygon_one_way` **(** :ref:`int` layer_id, :ref:`int` polygon_index, :ref:`bool` one_way **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_collision_polygon_one_way_margin` **(** :ref:`int` layer_id, :ref:`int` polygon_index, :ref:`float` one_way_margin **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_collision_polygon_points` **(** :ref:`int` layer_id, :ref:`int` polygon_index, :ref:`PackedVector2Array` polygon **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_collision_polygons_count` **(** :ref:`int` layer_id, :ref:`int` polygons_count **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_constant_angular_velocity` **(** :ref:`int` layer_id, :ref:`float` velocity **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_constant_linear_velocity` **(** :ref:`int` layer_id, :ref:`Vector2` velocity **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_custom_data` **(** :ref:`String` layer_name, :ref:`Variant` value **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_custom_data_by_layer_id` **(** :ref:`int` layer_id, :ref:`Variant` value **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_navigation_polygon` **(** :ref:`int` layer_id, :ref:`NavigationPolygon` navigation_polygon **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_occluder` **(** :ref:`int` layer_id, :ref:`OccluderPolygon2D` occluder_polygon **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`set_terrain_peering_bit` **(** :ref:`CellNeighbor` peering_bit, :ref:`int` terrain **)** | - +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`add_collision_polygon` **(** :ref:`int` layer_id **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_collision_polygon_one_way_margin` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`get_collision_polygon_points` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_collision_polygons_count` **(** :ref:`int` layer_id **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_constant_angular_velocity` **(** :ref:`int` layer_id **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_constant_linear_velocity` **(** :ref:`int` layer_id **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_custom_data` **(** :ref:`String` layer_name **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_custom_data_by_layer_id` **(** :ref:`int` layer_id **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`NavigationPolygon` | :ref:`get_navigation_polygon` **(** :ref:`int` layer_id, :ref:`bool` flip_h=false, :ref:`bool` flip_v=false, :ref:`bool` transpose=false **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`OccluderPolygon2D` | :ref:`get_occluder` **(** :ref:`int` layer_id, :ref:`bool` flip_h=false, :ref:`bool` flip_v=false, :ref:`bool` transpose=false **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_terrain_peering_bit` **(** :ref:`CellNeighbor` peering_bit **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_collision_polygon_one_way` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** |const| | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`remove_collision_polygon` **(** :ref:`int` layer_id, :ref:`int` polygon_index **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_collision_polygon_one_way` **(** :ref:`int` layer_id, :ref:`int` polygon_index, :ref:`bool` one_way **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_collision_polygon_one_way_margin` **(** :ref:`int` layer_id, :ref:`int` polygon_index, :ref:`float` one_way_margin **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_collision_polygon_points` **(** :ref:`int` layer_id, :ref:`int` polygon_index, :ref:`PackedVector2Array` polygon **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_collision_polygons_count` **(** :ref:`int` layer_id, :ref:`int` polygons_count **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_constant_angular_velocity` **(** :ref:`int` layer_id, :ref:`float` velocity **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_constant_linear_velocity` **(** :ref:`int` layer_id, :ref:`Vector2` velocity **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_custom_data` **(** :ref:`String` layer_name, :ref:`Variant` value **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_custom_data_by_layer_id` **(** :ref:`int` layer_id, :ref:`Variant` value **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_navigation_polygon` **(** :ref:`int` layer_id, :ref:`NavigationPolygon` navigation_polygon **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_occluder` **(** :ref:`int` layer_id, :ref:`OccluderPolygon2D` occluder_polygon **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_terrain_peering_bit` **(** :ref:`CellNeighbor` peering_bit, :ref:`int` terrain **)** | + +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -429,10 +429,12 @@ Returns the custom data value for custom data layer with index ``layer_id``. .. rst-class:: classref-method -:ref:`NavigationPolygon` **get_navigation_polygon** **(** :ref:`int` layer_id **)** |const| +:ref:`NavigationPolygon` **get_navigation_polygon** **(** :ref:`int` layer_id, :ref:`bool` flip_h=false, :ref:`bool` flip_v=false, :ref:`bool` transpose=false **)** |const| Returns the navigation polygon of the tile for the TileSet navigation layer with index ``layer_id``. +\ ``flip_h``, ``flip_v``, and ``transpose`` allow transforming the returned polygon. + .. rst-class:: classref-item-separator ---- @@ -441,10 +443,12 @@ Returns the navigation polygon of the tile for the TileSet navigation layer with .. rst-class:: classref-method -:ref:`OccluderPolygon2D` **get_occluder** **(** :ref:`int` layer_id **)** |const| +:ref:`OccluderPolygon2D` **get_occluder** **(** :ref:`int` layer_id, :ref:`bool` flip_h=false, :ref:`bool` flip_v=false, :ref:`bool` transpose=false **)** |const| Returns the occluder polygon of the tile for the TileSet occlusion layer with index ``layer_id``. +\ ``flip_h``, ``flip_v``, and ``transpose`` allow transforming the returned polygon. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_tilesetatlassource.rst b/classes/class_tilesetatlassource.rst index 8b2f0d31f48..30624c3f5ee 100644 --- a/classes/class_tilesetatlassource.rst +++ b/classes/class_tilesetatlassource.rst @@ -431,7 +431,7 @@ Returns how many animation frames has the tile at coordinates ``atlas_coords``. :ref:`TileAnimationMode` **get_tile_animation_mode** **(** :ref:`Vector2i` atlas_coords **)** |const| -Returns the :ref:`TileAnimationMode` of the tile at ``atlas_coords``. See also :ref:`set_tile_animation_mode`. +Returns the tile animation mode of the tile at ``atlas_coords``. See also :ref:`set_tile_animation_mode`. .. rst-class:: classref-item-separator @@ -655,7 +655,7 @@ Sets how many animation frames the tile at coordinates ``atlas_coords`` has. void **set_tile_animation_mode** **(** :ref:`Vector2i` atlas_coords, :ref:`TileAnimationMode` mode **)** -Sets the :ref:`TileAnimationMode` of the tile at ``atlas_coords`` to ``mode``. See also :ref:`get_tile_animation_mode`. +Sets the tile animation mode of the tile at ``atlas_coords`` to ``mode``. See also :ref:`get_tile_animation_mode`. .. rst-class:: classref-item-separator diff --git a/classes/class_transform2d.rst b/classes/class_transform2d.rst index cc9eb73dccc..eb7388fed4c 100644 --- a/classes/class_transform2d.rst +++ b/classes/class_transform2d.rst @@ -19,7 +19,7 @@ Description A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three :ref:`Vector2` values: :ref:`x`, :ref:`y`, and the :ref:`origin`. -For more information, read the "Matrices and transforms" documentation article. +For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. .. note:: @@ -149,6 +149,10 @@ Operators +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform2D` | :ref:`operator *` **(** :ref:`int` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`operator /` **(** :ref:`float` right **)** | + +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`operator /` **(** :ref:`int` right **)** | + +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`operator ==` **(** :ref:`Transform2D` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`operator []` **(** :ref:`int` index **)** | @@ -673,6 +677,30 @@ This operator multiplies all components of the **Transform2D**, including the :r ---- +.. _class_Transform2D_operator_div_float: + +.. rst-class:: classref-operator + +:ref:`Transform2D` **operator /** **(** :ref:`float` right **)** + +This operator divides all components of the **Transform2D**, including the :ref:`origin` vector, which inversely scales it uniformly. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Transform2D_operator_div_int: + +.. rst-class:: classref-operator + +:ref:`Transform2D` **operator /** **(** :ref:`int` right **)** + +This operator divides all components of the **Transform2D**, including the :ref:`origin` vector, which inversely scales it uniformly. + +.. rst-class:: classref-item-separator + +---- + .. _class_Transform2D_operator_eq_Transform2D: .. rst-class:: classref-operator diff --git a/classes/class_transform3d.rst b/classes/class_transform3d.rst index 68eb7cf7079..03930305ae9 100644 --- a/classes/class_transform3d.rst +++ b/classes/class_transform3d.rst @@ -19,7 +19,7 @@ Description A 3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of a :ref:`basis` (first 3 columns) and a :ref:`Vector3` for the :ref:`origin` (last column). -For more information, read the "Matrices and transforms" documentation article. +For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. .. note:: @@ -137,6 +137,10 @@ Operators +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Transform3D` | :ref:`operator *` **(** :ref:`int` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`operator /` **(** :ref:`float` right **)** | + +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`operator /` **(** :ref:`int` right **)** | + +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`operator ==` **(** :ref:`Transform3D` right **)** | +-----------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ @@ -567,6 +571,30 @@ This operator multiplies all components of the **Transform3D**, including the :r ---- +.. _class_Transform3D_operator_div_float: + +.. rst-class:: classref-operator + +:ref:`Transform3D` **operator /** **(** :ref:`float` right **)** + +This operator divides all components of the **Transform3D**, including the :ref:`origin` vector, which inversely scales it uniformly. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Transform3D_operator_div_int: + +.. rst-class:: classref-operator + +:ref:`Transform3D` **operator /** **(** :ref:`int` right **)** + +This operator divides all components of the **Transform3D**, including the :ref:`origin` vector, which inversely scales it uniformly. + +.. rst-class:: classref-item-separator + +---- + .. _class_Transform3D_operator_eq_Transform3D: .. rst-class:: classref-operator diff --git a/classes/class_tree.rst b/classes/class_tree.rst index 5228f1d0cc3..f16b6fe4889 100644 --- a/classes/class_tree.rst +++ b/classes/class_tree.rst @@ -186,125 +186,133 @@ Theme Properties .. table:: :widths: auto - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`children_hl_line_color` | ``Color(0.27, 0.27, 0.27, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`custom_button_font_highlight` | ``Color(0.95, 0.95, 0.95, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`drop_position_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`font_color` | ``Color(0.7, 0.7, 0.7, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`font_outline_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`font_selected_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`guide_color` | ``Color(0.7, 0.7, 0.7, 0.25)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`parent_hl_line_color` | ``Color(0.27, 0.27, 0.27, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`relationship_line_color` | ``Color(0.27, 0.27, 0.27, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Color` | :ref:`title_button_color` | ``Color(0.875, 0.875, 0.875, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`button_margin` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`children_hl_line_width` | ``1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`draw_guides` | ``1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`draw_relationship_lines` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`h_separation` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`icon_max_width` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`inner_item_margin_bottom` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`inner_item_margin_left` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`inner_item_margin_right` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`inner_item_margin_top` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`item_margin` | ``16`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`outline_size` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`parent_hl_line_margin` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`parent_hl_line_width` | ``1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`relationship_line_width` | ``1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scroll_border` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scroll_speed` | ``12`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scrollbar_h_separation` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scrollbar_margin_bottom` | ``-1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scrollbar_margin_left` | ``-1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scrollbar_margin_right` | ``-1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scrollbar_margin_top` | ``-1`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`scrollbar_v_separation` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`v_separation` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Font` | :ref:`font` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Font` | :ref:`title_button_font` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`font_size` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`int` | :ref:`title_button_font_size` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`arrow` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`arrow_collapsed` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`arrow_collapsed_mirrored` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`checked` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`indeterminate` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`select_arrow` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`unchecked` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`Texture2D` | :ref:`updown` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`button_pressed` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`cursor` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`cursor_unfocused` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`custom_button` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`custom_button_hover` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`custom_button_pressed` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`focus` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`panel` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`selected` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`selected_focus` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`title_button_hover` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`title_button_normal` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ - | :ref:`StyleBox` | :ref:`title_button_pressed` | | - +-----------------------------------+------------------------------------------------------------------------------------------+-----------------------------------+ + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`children_hl_line_color` | ``Color(0.27, 0.27, 0.27, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`custom_button_font_highlight` | ``Color(0.95, 0.95, 0.95, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`drop_position_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_color` | ``Color(0.7, 0.7, 0.7, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_disabled_color` | ``Color(0.875, 0.875, 0.875, 0.5)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_outline_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_selected_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`guide_color` | ``Color(0.7, 0.7, 0.7, 0.25)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`parent_hl_line_color` | ``Color(0.27, 0.27, 0.27, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`relationship_line_color` | ``Color(0.27, 0.27, 0.27, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`title_button_color` | ``Color(0.875, 0.875, 0.875, 1)`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`button_margin` | ``4`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`children_hl_line_width` | ``1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`draw_guides` | ``1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`draw_relationship_lines` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`h_separation` | ``4`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`icon_max_width` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`inner_item_margin_bottom` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`inner_item_margin_left` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`inner_item_margin_right` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`inner_item_margin_top` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`item_margin` | ``16`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`outline_size` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`parent_hl_line_margin` | ``0`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`parent_hl_line_width` | ``1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`relationship_line_width` | ``1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scroll_border` | ``4`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scroll_speed` | ``12`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scrollbar_h_separation` | ``4`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scrollbar_margin_bottom` | ``-1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scrollbar_margin_left` | ``-1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scrollbar_margin_right` | ``-1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scrollbar_margin_top` | ``-1`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`scrollbar_v_separation` | ``4`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`v_separation` | ``4`` | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Font` | :ref:`font` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Font` | :ref:`title_button_font` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`font_size` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`title_button_font_size` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`arrow` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`arrow_collapsed` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`arrow_collapsed_mirrored` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`checked` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`indeterminate` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`indeterminate_disabled` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`select_arrow` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`unchecked` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`updown` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`button_pressed` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`cursor` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`cursor_unfocused` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`custom_button` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`custom_button_hover` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`custom_button_pressed` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`focus` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`panel` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`selected` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`selected_focus` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`title_button_hover` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`title_button_normal` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`title_button_pressed` | | + +-----------------------------------+------------------------------------------------------------------------------------------+-------------------------------------+ .. rst-class:: classref-section-separator @@ -1344,6 +1352,18 @@ Default text :ref:`Color` of the item. ---- +.. _class_Tree_theme_color_font_disabled_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **font_disabled_color** = ``Color(0.875, 0.875, 0.875, 0.5)`` + +Text :ref:`Color` for a :ref:`TreeItem.CELL_MODE_CHECK` mode cell when it's non-editable (see :ref:`TreeItem.set_editable`). + +.. rst-class:: classref-item-separator + +---- + .. _class_Tree_theme_color_font_outline_color: .. rst-class:: classref-themeproperty @@ -1796,7 +1816,19 @@ The arrow icon used when a foldable item is collapsed (for right-to-left layouts :ref:`Texture2D` **checked** -The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is checked. +The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is checked and editable (see :ref:`TreeItem.set_editable`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Tree_theme_icon_checked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **checked_disabled** + +The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is checked and non-editable (see :ref:`TreeItem.set_editable`). .. rst-class:: classref-item-separator @@ -1808,7 +1840,19 @@ The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` **indeterminate** -The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is indeterminate. +The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is indeterminate and editable (see :ref:`TreeItem.set_editable`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Tree_theme_icon_indeterminate_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **indeterminate_disabled** + +The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is indeterminate and non-editable (see :ref:`TreeItem.set_editable`). .. rst-class:: classref-item-separator @@ -1832,7 +1876,19 @@ The arrow icon to display for the :ref:`TreeItem.CELL_MODE_RANGE` **unchecked** -The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is unchecked. +The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is unchecked and editable (see :ref:`TreeItem.set_editable`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Tree_theme_icon_unchecked_disabled: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **unchecked_disabled** + +The check icon to display when the :ref:`TreeItem.CELL_MODE_CHECK` mode cell is unchecked and non-editable (see :ref:`TreeItem.set_editable`). .. rst-class:: classref-item-separator diff --git a/classes/class_vector2i.rst b/classes/class_vector2i.rst index 56b3dfdb12f..bb3fb590b6a 100644 --- a/classes/class_vector2i.rst +++ b/classes/class_vector2i.rst @@ -81,6 +81,10 @@ Methods +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`clamp` **(** :ref:`Vector2i` min, :ref:`Vector2i` max **)** |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`distance_squared_to` **(** :ref:`Vector2i` to **)** |const| | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`distance_to` **(** :ref:`Vector2i` to **)** |const| | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`length` **(** **)** |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`length_squared` **(** **)** |const| | @@ -352,6 +356,32 @@ Returns a new vector with all components clamped between the components of ``min ---- +.. _class_Vector2i_method_distance_squared_to: + +.. rst-class:: classref-method + +:ref:`int` **distance_squared_to** **(** :ref:`Vector2i` to **)** |const| + +Returns the squared distance between this vector and ``to``. + +This method runs faster than :ref:`distance_to`, so prefer it if you need to compare vectors or need the squared distance for some formula. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Vector2i_method_distance_to: + +.. rst-class:: classref-method + +:ref:`float` **distance_to** **(** :ref:`Vector2i` to **)** |const| + +Returns the distance between this vector and ``to``. + +.. rst-class:: classref-item-separator + +---- + .. _class_Vector2i_method_length: .. rst-class:: classref-method diff --git a/classes/class_vector3i.rst b/classes/class_vector3i.rst index f5bf5c78bc8..a881ea5c799 100644 --- a/classes/class_vector3i.rst +++ b/classes/class_vector3i.rst @@ -81,6 +81,10 @@ Methods +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3i` | :ref:`clamp` **(** :ref:`Vector3i` min, :ref:`Vector3i` max **)** |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`distance_squared_to` **(** :ref:`Vector3i` to **)** |const| | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`distance_to` **(** :ref:`Vector3i` to **)** |const| | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`length` **(** **)** |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`length_squared` **(** **)** |const| | @@ -376,6 +380,32 @@ Returns a new vector with all components clamped between the components of ``min ---- +.. _class_Vector3i_method_distance_squared_to: + +.. rst-class:: classref-method + +:ref:`int` **distance_squared_to** **(** :ref:`Vector3i` to **)** |const| + +Returns the squared distance between this vector and ``to``. + +This method runs faster than :ref:`distance_to`, so prefer it if you need to compare vectors or need the squared distance for some formula. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Vector3i_method_distance_to: + +.. rst-class:: classref-method + +:ref:`float` **distance_to** **(** :ref:`Vector3i` to **)** |const| + +Returns the distance between this vector and ``to``. + +.. rst-class:: classref-item-separator + +---- + .. _class_Vector3i_method_length: .. rst-class:: classref-method diff --git a/classes/class_vector4i.rst b/classes/class_vector4i.rst index 6b98458efd7..4b2fea1f6d3 100644 --- a/classes/class_vector4i.rst +++ b/classes/class_vector4i.rst @@ -72,6 +72,10 @@ Methods +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector4i` | :ref:`clamp` **(** :ref:`Vector4i` min, :ref:`Vector4i` max **)** |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`distance_squared_to` **(** :ref:`Vector4i` to **)** |const| | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`distance_to` **(** :ref:`Vector4i` to **)** |const| | + +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`length` **(** **)** |const| | +---------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`length_squared` **(** **)** |const| | @@ -339,6 +343,32 @@ Returns a new vector with all components clamped between the components of ``min ---- +.. _class_Vector4i_method_distance_squared_to: + +.. rst-class:: classref-method + +:ref:`int` **distance_squared_to** **(** :ref:`Vector4i` to **)** |const| + +Returns the squared distance between this vector and ``to``. + +This method runs faster than :ref:`distance_to`, so prefer it if you need to compare vectors or need the squared distance for some formula. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Vector4i_method_distance_to: + +.. rst-class:: classref-method + +:ref:`float` **distance_to** **(** :ref:`Vector4i` to **)** |const| + +Returns the distance between this vector and ``to``. + +.. rst-class:: classref-item-separator + +---- + .. _class_Vector4i_method_length: .. rst-class:: classref-method diff --git a/classes/class_vehiclewheel3d.rst b/classes/class_vehiclewheel3d.rst index 7e8612be9f9..5ae487e5e56 100644 --- a/classes/class_vehiclewheel3d.rst +++ b/classes/class_vehiclewheel3d.rst @@ -333,7 +333,7 @@ This is the distance in meters the wheel is lowered from its origin point. Don't - void **set_roll_influence** **(** :ref:`float` value **)** - :ref:`float` **get_roll_influence** **(** **)** -This value affects the roll of your vehicle. If set to 1.0 for all wheels, your vehicle will be prone to rolling over, while a value of 0.0 will resist body roll. +This value affects the roll of your vehicle. If set to 1.0 for all wheels, your vehicle will resist body roll, while a value of 0.0 will be prone to rolling over. .. rst-class:: classref-section-separator diff --git a/classes/class_videostreamplayer.rst b/classes/class_videostreamplayer.rst index 901b798505b..79901416ab2 100644 --- a/classes/class_videostreamplayer.rst +++ b/classes/class_videostreamplayer.rst @@ -23,8 +23,6 @@ A control used for playback of :ref:`VideoStream` resources. Supported video formats are `Ogg Theora `__ (``.ogv``, :ref:`VideoStreamTheora`) and any format exposed via a GDExtension plugin. -\ **Note:** Due to a bug, VideoStreamPlayer does not support localization remapping yet. - \ **Warning:** On Web, video playback *will* perform poorly due to missing architecture-specific assembly optimizations. .. rst-class:: classref-introduction-group diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index 62d8d61b1e3..fcf3ee56d3a 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -191,6 +191,8 @@ Methods +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Control` | :ref:`gui_get_focus_owner` **(** **)** |const| | +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`gui_get_hovered_control` **(** **)** |const| | + +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`gui_is_drag_successful` **(** **)** |const| | +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`gui_is_dragging` **(** **)** |const| | @@ -768,7 +770,7 @@ enum **DefaultCanvasItemTextureFilter**: :ref:`DefaultCanvasItemTextureFilter` **DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST** = ``0`` -The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_Viewport_constant_DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR: @@ -776,7 +778,7 @@ The texture filter reads from the nearest pixel only. The simplest and fastest m :ref:`DefaultCanvasItemTextureFilter` **DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR** = ``1`` -The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_Viewport_constant_DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS: @@ -784,7 +786,9 @@ The texture filter blends between the nearest 4 pixels. Use this when you want t :ref:`DefaultCanvasItemTextureFilter` **DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``2`` -The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_Viewport_constant_DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS: @@ -792,7 +796,9 @@ The texture filter reads from the nearest pixel in the nearest mipmap. The faste :ref:`DefaultCanvasItemTextureFilter` **DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``3`` -The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_Viewport_constant_DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_MAX: @@ -1907,7 +1913,7 @@ Returns the mouse's position in this **Viewport** using the coordinate system of :ref:`PositionalShadowAtlasQuadrantSubdiv` **get_positional_shadow_atlas_quadrant_subdiv** **(** :ref:`int` quadrant **)** |const| -Returns the :ref:`PositionalShadowAtlasQuadrantSubdiv` of the specified quadrant. +Returns the positional shadow atlas quadrant subdivision of the specified quadrant. .. rst-class:: classref-item-separator @@ -2005,6 +2011,20 @@ Returns the :ref:`Control` having the focus within this viewport. ---- +.. _class_Viewport_method_gui_get_hovered_control: + +.. rst-class:: classref-method + +:ref:`Control` **gui_get_hovered_control** **(** **)** |const| + +Returns the :ref:`Control` that the mouse is currently hovering over in this viewport. If no :ref:`Control` has the cursor, returns null. + +Typically the leaf :ref:`Control` node or deepest level of the subtree which claims hover. This is very useful when used together with :ref:`Node.is_ancestor_of` to find if the mouse is within a control tree. + +.. rst-class:: classref-item-separator + +---- + .. _class_Viewport_method_gui_is_drag_successful: .. rst-class:: classref-method diff --git a/classes/class_visualshadernodetextureparameter.rst b/classes/class_visualshadernodetextureparameter.rst index 9ba2f704b75..b0baaedae4e 100644 --- a/classes/class_visualshadernodetextureparameter.rst +++ b/classes/class_visualshadernodetextureparameter.rst @@ -164,7 +164,7 @@ Sample the texture using the filter determined by the node this shader is attach :ref:`TextureFilter` **FILTER_NEAREST** = ``1`` -The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. +The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_VisualShaderNodeTextureParameter_constant_FILTER_LINEAR: @@ -172,7 +172,7 @@ The texture filter reads from the nearest pixel only. The simplest and fastest m :ref:`TextureFilter` **FILTER_LINEAR** = ``2`` -The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. +The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). .. _class_VisualShaderNodeTextureParameter_constant_FILTER_NEAREST_MIPMAP: @@ -180,7 +180,9 @@ The texture filter blends between the nearest four pixels. Use this for most cas :ref:`TextureFilter` **FILTER_NEAREST_MIPMAP** = ``3`` -The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps. +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_VisualShaderNodeTextureParameter_constant_FILTER_LINEAR_MIPMAP: @@ -188,7 +190,9 @@ The texture filter reads from the nearest pixel in the nearest mipmap. This is t :ref:`TextureFilter` **FILTER_LINEAR_MIPMAP** = ``4`` -The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to :ref:`Camera2D` zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. .. _class_VisualShaderNodeTextureParameter_constant_FILTER_NEAREST_MIPMAP_ANISOTROPIC: @@ -196,9 +200,9 @@ The texture filter blends between the nearest 4 pixels and between the nearest 2 :ref:`TextureFilter` **FILTER_NEAREST_MIPMAP_ANISOTROPIC** = ``5`` -The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. -\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`FILTER_LINEAR_MIPMAP` is usually more appropriate. +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`FILTER_NEAREST_MIPMAP` is usually more appropriate in this case. .. _class_VisualShaderNodeTextureParameter_constant_FILTER_LINEAR_MIPMAP_ANISOTROPIC: @@ -206,9 +210,9 @@ The texture filter reads from the nearest pixel, but selects a mipmap based on t :ref:`TextureFilter` **FILTER_LINEAR_MIPMAP_ANISOTROPIC** = ``6`` -The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level`. -\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`FILTER_LINEAR_MIPMAP` is usually more appropriate. +\ **Note:** This texture filter is rarely useful in 2D projects. :ref:`FILTER_LINEAR_MIPMAP` is usually more appropriate in this case. .. _class_VisualShaderNodeTextureParameter_constant_FILTER_MAX: diff --git a/classes/class_webrtcpeerconnection.rst b/classes/class_webrtcpeerconnection.rst index 7188fdf4a9a..bbde093947d 100644 --- a/classes/class_webrtcpeerconnection.rst +++ b/classes/class_webrtcpeerconnection.rst @@ -376,7 +376,7 @@ Returns the ICE :ref:`GatheringState` :ref:`SignalingState` **get_signaling_state** **(** **)** |const| -Returns the :ref:`SignalingState` on the local end of the connection while connecting or reconnecting to another peer. +Returns the signaling state on the local end of the connection while connecting or reconnecting to another peer. .. rst-class:: classref-item-separator diff --git a/classes/class_workerthreadpool.rst b/classes/class_workerthreadpool.rst index 6e2cda3d480..81a325ac7ca 100644 --- a/classes/class_workerthreadpool.rst +++ b/classes/class_workerthreadpool.rst @@ -200,7 +200,7 @@ Returns :ref:`@GlobalScope.OK` if the task could Returns :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if a task with the passed ID does not exist (maybe because it was already awaited and disposed of). -Returns :ref:`@GlobalScope.ERR_BUSY` if the call is made from another running task and, due to task scheduling, the task to await is at a lower level in the call stack and therefore can't progress. This is an advanced situation that should only matter when some tasks depend on others. +Returns :ref:`@GlobalScope.ERR_BUSY` if the call is made from another running task and, due to task scheduling, there's potential for deadlocking (e.g., the task to await may be at a lower level in the call stack and therefore can't progress). This is an advanced situation that should only matter when some tasks depend on others (in the current implementation, the tricky case is a task trying to wait on an older one). .. |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_xrinterface.rst b/classes/class_xrinterface.rst index c535049adbd..09cd1f9cfeb 100644 --- a/classes/class_xrinterface.rst +++ b/classes/class_xrinterface.rst @@ -610,7 +610,7 @@ Is ``true`` if this interface supports passthrough. Sets the active environment blend mode. -\ ``mode`` is the :ref:`EnvironmentBlendMode` starting with the next frame. +\ ``mode`` is the environment blend mode starting with the next frame. \ **Note:** Not all runtimes support all environment blend modes, so it is important to check this at startup. For example: diff --git a/classes/class_xrinterfaceextension.rst b/classes/class_xrinterfaceextension.rst index ede44829506..d0de1b03526 100644 --- a/classes/class_xrinterfaceextension.rst +++ b/classes/class_xrinterfaceextension.rst @@ -233,7 +233,7 @@ Returns an :ref:`PackedVector3Array` that denotes the :ref:`PlayAreaMode` **_get_play_area_mode** **(** **)** |virtual| |const| -Returns the :ref:`PlayAreaMode` that sets up our play area. +Returns the play area mode that sets up our play area. .. rst-class:: classref-item-separator