From de1b79e21f58cce3817b353e495812e99aad94fd Mon Sep 17 00:00:00 2001 From: Godot Organization Date: Sat, 6 Jan 2024 03:19:33 +0000 Subject: [PATCH] classref: Sync with current master branch (89cc635) --- classes/class_@gdscript.rst | 2 +- classes/class_@globalscope.rst | 16 +- classes/class_array.rst | 2 + classes/class_astargrid2d.rst | 61 +++ classes/class_basematerial3d.rst | 2 +- classes/class_basis.rst | 210 ++++++++- classes/class_callable.rst | 13 - classes/class_cameraattributespractical.rst | 2 +- classes/class_colorpicker.rst | 14 + classes/class_compressedcubemap.rst | 2 +- classes/class_compressedcubemaparray.rst | 2 +- classes/class_compressedtexture2darray.rst | 2 +- classes/class_curve2d.rst | 10 +- classes/class_editorexportplatformios.rst | 208 ++------- classes/class_editorinspector.rst | 2 + classes/class_editorplugin.rst | 2 +- classes/class_geometry3d.rst | 14 + classes/class_gltfdocument.rst | 2 +- classes/class_image.rst | 2 +- classes/class_inputeventmidi.rst | 2 +- classes/class_lightmapgi.rst | 19 + classes/class_navigationserver3d.rst | 2 +- classes/class_node.rst | 471 +++++++++++--------- classes/class_nodepath.rst | 4 +- classes/class_object.rst | 2 +- classes/class_os.rst | 371 +++++++++------ classes/class_packedbytearray.rst | 2 +- classes/class_packedcolorarray.rst | 2 +- classes/class_packedfloat32array.rst | 2 +- classes/class_packedfloat64array.rst | 2 +- classes/class_packedint32array.rst | 2 +- classes/class_packedint64array.rst | 2 +- classes/class_packedstringarray.rst | 2 +- classes/class_packedvector2array.rst | 2 +- classes/class_packedvector3array.rst | 2 +- classes/class_projectsettings.rst | 36 +- classes/class_quaternion.rst | 16 +- classes/class_renderingdevice.rst | 2 +- classes/class_scriptlanguageextension.rst | 8 +- classes/class_string.rst | 2 +- classes/class_stringname.rst | 2 +- classes/class_texture2d.rst | 2 + classes/class_transform2d.rst | 30 +- classes/class_transform3d.rst | 30 +- classes/class_vector2i.rst | 30 ++ classes/class_vector3i.rst | 30 ++ classes/class_vector4i.rst | 30 ++ classes/class_vehiclewheel3d.rst | 2 +- 48 files changed, 1056 insertions(+), 621 deletions(-) diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index f0e4c9749b0..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. :: diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index f02151c1c54..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 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_basematerial3d.rst b/classes/class_basematerial3d.rst index 2b32099288a..5de49da36e3 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -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_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_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_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_editorexportplatformios.rst b/classes/class_editorexportplatformios.rst index 87d7574541f..09398d58cc2 100644 --- a/classes/class_editorexportplatformios.rst +++ b/classes/class_editorexportplatformios.rst @@ -48,7 +48,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 +66,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 +100,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 +122,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` | @@ -252,13 +232,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 +344,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 +552,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 +684,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_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_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_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_image.rst b/classes/class_image.rst index 68a47239f37..55f1a5b6a35 100644 --- a/classes/class_image.rst +++ b/classes/class_image.rst @@ -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 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_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_navigationserver3d.rst b/classes/class_navigationserver3d.rst index 28cf9083e7d..aef0e400a3f 100644 --- a/classes/class_navigationserver3d.rst +++ b/classes/class_navigationserver3d.rst @@ -885,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. diff --git a/classes/class_node.rst b/classes/class_node.rst index e95fc85feca..b2176c40507 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. -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 @@ -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_os.rst b/classes/class_os.rst index 855b9a91192..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 @@ -239,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: @@ -247,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: @@ -255,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: @@ -263,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: @@ -271,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: @@ -279,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: @@ -287,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: @@ -295,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 @@ -317,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 @@ -336,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 ---- @@ -351,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 @@ -368,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 @@ -380,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. @@ -394,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 @@ -408,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 @@ -422,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: @@ -459,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). @@ -475,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). @@ -491,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: @@ -553,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 @@ -565,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. @@ -587,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:: @@ -596,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: @@ -609,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]; @@ -624,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 @@ -636,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 @@ -656,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. @@ -670,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. @@ -686,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. @@ -700,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 @@ -718,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 ---- @@ -732,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. @@ -746,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 @@ -760,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`. + -See also :ref:`InputEventKey.keycode` and :ref:`InputEventKey.get_keycode_with_modifiers`. +.. 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:`find_keycode_from_string`, :ref:`InputEventKey.keycode`, and :ref:`InputEventKey.get_keycode_with_modifiers`. .. rst-class:: classref-item-separator @@ -774,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 @@ -824,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 @@ -858,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:: @@ -883,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 ---- @@ -935,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. @@ -961,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. @@ -987,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 @@ -999,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 @@ -1011,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 @@ -1027,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". @@ -1045,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". @@ -1065,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. @@ -1095,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 @@ -1109,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]``. @@ -1137,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 @@ -1157,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 @@ -1193,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 @@ -1211,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 @@ -1223,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 @@ -1235,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. @@ -1263,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 @@ -1289,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 @@ -1301,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. @@ -1317,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:: @@ -1338,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 ---- @@ -1348,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. @@ -1376,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 @@ -1388,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 @@ -1428,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. @@ -1446,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 @@ -1458,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 @@ -1470,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. @@ -1478,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. @@ -1494,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 @@ -1512,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_projectsettings.rst b/classes/class_projectsettings.rst index 7d9e570ae58..64c692e3e16 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`` | @@ -1453,6 +1451,8 @@ 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`` | @@ -4934,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 @@ -5336,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. @@ -5350,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. @@ -5364,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. @@ -8368,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 @@ -10634,6 +10622,18 @@ 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 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_renderingdevice.rst b/classes/class_renderingdevice.rst index cd5114f1cd2..46c80fb40b1 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -4722,7 +4722,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. diff --git a/classes/class_scriptlanguageextension.rst b/classes/class_scriptlanguageextension.rst index 003acd4ca94..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| | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -610,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| +:ref:`int` **_find_function** **(** :ref:`String` function, :ref:`String` code **)** |virtual| |const| -.. container:: contribute - - 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 diff --git a/classes/class_string.rst b/classes/class_string.rst index 15a10337844..13ac848e1be 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -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 diff --git a/classes/class_stringname.rst b/classes/class_stringname.rst index 78f95eaec21..2b9142be6b5 100644 --- a/classes/class_stringname.rst +++ b/classes/class_stringname.rst @@ -753,7 +753,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 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_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_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