diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 8f5734bb6..cd31e64ba 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -10,7 +10,7 @@ @GDScript ========= -Built-in GDScript functions. +Built-in GDScript constants, functions, and annotations. .. rst-class:: classref-introduction-group @@ -109,7 +109,7 @@ Positive floating-point infinity. This is the result of floating-point division **NAN** = ``nan`` -"Not a Number", an invalid floating-point value. :ref:`NAN` has special properties, including that it is not equal to itself (``NAN == NAN`` returns ``false``). It is output by some invalid operations, such as dividing floating-point ``0.0`` by ``0.0``. +"Not a Number", an invalid floating-point value. :ref:`NAN` has special properties, including that ``!=`` always returns ``true``, while other comparison operators always return ``false``. This is true even when comparing with itself (``NAN == NAN`` returns ``false`` and ``NAN != NAN`` returns ``true``). It is returned by some invalid operations, such as dividing floating-point ``0.0`` by ``0.0``. \ **Warning:** "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer ``0`` by ``0`` will not result in :ref:`NAN` and will result in a run-time error instead. diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 15f95d382..13596225a 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -6214,7 +6214,7 @@ The following BBCode tags are supported: ``b``, ``i``, ``u``, ``s``, ``indent``, Color tags only support the following named colors: ``black``, ``red``, ``green``, ``yellow``, ``blue``, ``magenta``, ``pink``, ``purple``, ``cyan``, ``white``, ``orange``, ``gray``. Hexadecimal color codes are not supported. -URL tags only support URLs wrapped by an URL tag, not URLs with a different title. +URL tags only support URLs wrapped by a URL tag, not URLs with a different title. When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, ``code`` is represented with faint text but without any font change. Unsupported tags are left as-is in standard output. diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index ec4898e0a..39c69a9fb 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -10,7 +10,7 @@ AABB ==== -Axis-Aligned Bounding Box. +A 3D axis-aligned bounding box. .. rst-class:: classref-introduction-group diff --git a/classes/class_acceptdialog.rst b/classes/class_acceptdialog.rst index e8fc3da23..e135dd861 100644 --- a/classes/class_acceptdialog.rst +++ b/classes/class_acceptdialog.rst @@ -14,14 +14,14 @@ AcceptDialog **Inherited By:** :ref:`ConfirmationDialog` -Base dialog for user notification. +A base dialog used for user notification. .. rst-class:: classref-introduction-group Description ----------- -This dialog is useful for small notifications to the user about an event. It can only be accepted or closed, with the same result. +The default use of **AcceptDialog** is to allow it to only be accepted or closed, with the same result. However, the :ref:`confirmed` and :ref:`canceled` signals allow to make the two actions different, and the :ref:`add_button` method allows to add custom buttons and actions. .. rst-class:: classref-reftable-group diff --git a/classes/class_aescontext.rst b/classes/class_aescontext.rst index 4cf97b699..9ca4695d9 100644 --- a/classes/class_aescontext.rst +++ b/classes/class_aescontext.rst @@ -12,14 +12,14 @@ AESContext **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Interface to low level AES encryption features. +Provides access to AES encryption/decryption of raw data. .. rst-class:: classref-introduction-group Description ----------- -This class provides access to AES encryption/decryption of raw data. Both AES-ECB and AES-CBC mode are supported. +This class holds the context information required for encryption and decryption operations with AES (Advanced Encryption Standard). Both AES-ECB and AES-CBC modes are supported. .. tabs:: diff --git a/classes/class_animation.rst b/classes/class_animation.rst index eb6a271da..162bc9b44 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -12,14 +12,14 @@ Animation **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Contains data used to animate everything in the engine. +Holds data that can be used to animate anything in the engine. .. rst-class:: classref-introduction-group Description ----------- -An Animation resource contains data used to animate everything in the engine. Animations are divided into tracks, and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track. +This resource holds data that can be used to animate anything in the engine. Animations are divided into tracks and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track. .. tabs:: diff --git a/classes/class_animationnode.rst b/classes/class_animationnode.rst index 68228c432..964e0acf4 100644 --- a/classes/class_animationnode.rst +++ b/classes/class_animationnode.rst @@ -14,7 +14,7 @@ AnimationNode **Inherited By:** :ref:`AnimationNodeOutput`, :ref:`AnimationNodeSync`, :ref:`AnimationNodeTimeScale`, :ref:`AnimationNodeTimeSeek`, :ref:`AnimationRootNode` -Base resource for :ref:`AnimationTree` nodes. +Base class for :ref:`AnimationTree` nodes. Not related to scene nodes. .. rst-class:: classref-introduction-group @@ -30,7 +30,7 @@ Inherit this when creating nodes mainly for use in :ref:`AnimationNodeBlendTree< Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodeadd2.rst b/classes/class_animationnodeadd2.rst index 57f00ac3b..faf97600c 100644 --- a/classes/class_animationnodeadd2.rst +++ b/classes/class_animationnodeadd2.rst @@ -26,7 +26,7 @@ A resource to add to an :ref:`AnimationNodeBlendTree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |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_animationnodeadd3.rst b/classes/class_animationnodeadd3.rst index 80654319b..25004f371 100644 --- a/classes/class_animationnodeadd3.rst +++ b/classes/class_animationnodeadd3.rst @@ -34,7 +34,7 @@ This node has three inputs: Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `Third Person Shooter Demo `__ diff --git a/classes/class_animationnodeanimation.rst b/classes/class_animationnodeanimation.rst index b4cf540c5..946cc375a 100644 --- a/classes/class_animationnodeanimation.rst +++ b/classes/class_animationnodeanimation.rst @@ -12,21 +12,21 @@ AnimationNodeAnimation **Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input animation to use in an :ref:`AnimationNodeBlendTree`. +An input animation for an :ref:`AnimationNodeBlendTree`. .. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Only features one output set using the :ref:`animation` property. Use it as an input for :ref:`AnimationNode` that blend animations together. +A resource to add to an :ref:`AnimationNodeBlendTree`. Only has one output port using the :ref:`animation` property. Used as an input for :ref:`AnimationNode`\ s that blend animations together. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `3D Platformer Demo `__ diff --git a/classes/class_animationnodeblend2.rst b/classes/class_animationnodeblend2.rst index 1bfb51ef0..add179093 100644 --- a/classes/class_animationnodeblend2.rst +++ b/classes/class_animationnodeblend2.rst @@ -26,7 +26,7 @@ A resource to add to an :ref:`AnimationNodeBlendTree` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `3D Platformer Demo `__ diff --git a/classes/class_animationnodeblend3.rst b/classes/class_animationnodeblend3.rst index 0b98238c1..6e740475b 100644 --- a/classes/class_animationnodeblend3.rst +++ b/classes/class_animationnodeblend3.rst @@ -34,7 +34,7 @@ This node has three inputs: Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |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_animationnodeblendspace1d.rst b/classes/class_animationnodeblendspace1d.rst index 43047c87a..17437887e 100644 --- a/classes/class_animationnodeblendspace1d.rst +++ b/classes/class_animationnodeblendspace1d.rst @@ -12,27 +12,25 @@ AnimationNodeBlendSpace1D **Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Blends linearly between two of any number of :ref:`AnimationNode` of any type placed on a virtual axis. +A set of :ref:`AnimationRootNode`\ s placed on a virtual axis, crossfading between the two adjacent ones. Used by :ref:`AnimationTree`. .. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. +A resource used by :ref:`AnimationNodeBlendTree`. -This is a virtual axis on which you can add any type of :ref:`AnimationNode` using :ref:`add_blend_point`. +\ **AnimationNodeBlendSpace1D** represents a virtual axis on which any type of :ref:`AnimationRootNode`\ s can be added using :ref:`add_blend_point`. Outputs the linear blend of the two :ref:`AnimationRootNode`\ s adjacent to the current value. -Outputs the linear blend of the two :ref:`AnimationNode`\ s closest to the node's current value. - -You can set the extents of the axis using the :ref:`min_space` and :ref:`max_space`. +You can set the extents of the axis with :ref:`min_space` and :ref:`max_space`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodeblendspace2d.rst b/classes/class_animationnodeblendspace2d.rst index 1df9a6b07..7b5a1f7d4 100644 --- a/classes/class_animationnodeblendspace2d.rst +++ b/classes/class_animationnodeblendspace2d.rst @@ -12,25 +12,25 @@ AnimationNodeBlendSpace2D **Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Blends linearly between three :ref:`AnimationNode` of any type placed in a 2D space. +A set of :ref:`AnimationRootNode`\ s placed on 2D coordinates, crossfading between the three adjacent ones. Used by :ref:`AnimationTree`. .. rst-class:: classref-introduction-group Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. +A resource used by :ref:`AnimationNodeBlendTree`. -This node allows you to blend linearly between three animations using a :ref:`Vector2` weight. +\ :ref:`AnimationNodeBlendSpace1D` represents a virtual 2D space on which :ref:`AnimationRootNode`\ s are placed. Outputs the linear blend of the three adjacent animations using a :ref:`Vector2` weight. Adjacent in this context means the three :ref:`AnimationRootNode`\ s making up the triangle that contains the current value. -You can add vertices to the blend space with :ref:`add_blend_point` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle` and :ref:`remove_triangle` to create up the blend space by hand. +You can add vertices to the blend space with :ref:`add_blend_point` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle` and :ref:`remove_triangle` to triangulate the blend space by hand. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `Third Person Shooter Demo `__ diff --git a/classes/class_animationnodeblendtree.rst b/classes/class_animationnodeblendtree.rst index bee5d76cd..35c9e8bc9 100644 --- a/classes/class_animationnodeblendtree.rst +++ b/classes/class_animationnodeblendtree.rst @@ -12,14 +12,14 @@ AnimationNodeBlendTree **Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`AnimationTree` node resource that contains many blend type nodes. +A sub-tree of blend type :ref:`AnimationNode`\ s used for complex animations. Used by :ref:`AnimationTree`. .. rst-class:: classref-introduction-group Description ----------- -This node may contain a sub-tree of any other blend type nodes, such as :ref:`AnimationNodeTransition`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, etc. This is one of the most commonly used roots. +This node may contain a sub-tree of any other blend type nodes, such as :ref:`AnimationNodeTransition`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, etc. This is one of the most commonly used animation node roots. An :ref:`AnimationNodeOutput` node named ``output`` is created by default. @@ -28,7 +28,7 @@ An :ref:`AnimationNodeOutput` node named ``output`` i Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index 18785618a..0970e38b0 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -12,7 +12,7 @@ AnimationNodeOneShot **Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Plays an animation once in :ref:`AnimationNodeBlendTree`. +Plays an animation once in an :ref:`AnimationNodeBlendTree`. .. rst-class:: classref-introduction-group @@ -46,10 +46,10 @@ After setting the request and changing the animation playback, the one-shot node .. code-tab:: csharp // Play child animation connected to "shot" port. - animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE); + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Fire); // Abort child animation connected to "shot" port. - animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT); + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Abort); // Get current state (read-only). animationTree.Get("parameters/OneShot/active"); @@ -61,7 +61,7 @@ After setting the request and changing the animation playback, the one-shot node Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `Third Person Shooter Demo `__ diff --git a/classes/class_animationnodeoutput.rst b/classes/class_animationnodeoutput.rst index 007228f76..5fadf0e18 100644 --- a/classes/class_animationnodeoutput.rst +++ b/classes/class_animationnodeoutput.rst @@ -12,14 +12,21 @@ AnimationNodeOutput **Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Generic output node to be added to :ref:`AnimationNodeBlendTree`. +The animation output node of an :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A node created automatically in an :ref:`AnimationNodeBlendTree` that outputs the final animation. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `3D Platformer Demo `__ diff --git a/classes/class_animationnodestatemachine.rst b/classes/class_animationnodestatemachine.rst index 1926fd3e3..97377ed5d 100644 --- a/classes/class_animationnodestatemachine.rst +++ b/classes/class_animationnodestatemachine.rst @@ -12,14 +12,14 @@ AnimationNodeStateMachine **Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -State machine for control of animations. +A state machine with multiple :ref:`AnimationRootNode`\ s, used by :ref:`AnimationTree`. .. rst-class:: classref-introduction-group Description ----------- -Contains multiple nodes representing animation states, connected in a graph. Node transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. +Contains multiple :ref:`AnimationRootNode`\ s representing animation states, connected in a graph. Node transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. \ **Example:**\ @@ -43,7 +43,7 @@ Contains multiple nodes representing animation states, connected in a graph. Nod Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index bc55e3a11..f7c537357 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -12,7 +12,7 @@ AnimationNodeStateMachinePlayback **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Playback control for :ref:`AnimationNodeStateMachine`. +Provides playback control for an :ref:`AnimationNodeStateMachine`. .. rst-class:: classref-introduction-group @@ -33,7 +33,7 @@ Allows control of :ref:`AnimationTree` state machines creat .. code-tab:: csharp - var stateMachine = GetNode("AnimationTree").Get("parameters/playback") as AnimationNodeStateMachinePlayback; + var stateMachine = GetNode("AnimationTree").Get("parameters/playback").As(); stateMachine.Travel("some_state"); @@ -43,7 +43,7 @@ Allows control of :ref:`AnimationTree` state machines creat Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index be533df2c..8aa8b38b1 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -12,7 +12,7 @@ AnimationNodeStateMachineTransition **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A resource to connect each node to make a path for :ref:`AnimationNodeStateMachine`. +A transition within an :ref:`AnimationNodeStateMachine` connecting two :ref:`AnimationRootNode`\ s. .. rst-class:: classref-introduction-group @@ -28,7 +28,7 @@ You can set the timing and conditions of the transition in detail. Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodesync.rst b/classes/class_animationnodesync.rst index 6bbea2d95..fec585eee 100644 --- a/classes/class_animationnodesync.rst +++ b/classes/class_animationnodesync.rst @@ -14,7 +14,21 @@ AnimationNodeSync **Inherited By:** :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, :ref:`AnimationNodeTransition` -The base class for :ref:`AnimationNode` which has more than two input ports and needs to synchronize them. +Base class for :ref:`AnimationNode`\ s with more than two input ports that must be synchronized. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An animation node used to combine, mix, or blend two or more animations together while keeping them synchronized within an :ref:`AnimationTree`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. rst-class:: classref-reftable-group diff --git a/classes/class_animationnodetimescale.rst b/classes/class_animationnodetimescale.rst index 3a9dcbd5b..10f8c881a 100644 --- a/classes/class_animationnodetimescale.rst +++ b/classes/class_animationnodetimescale.rst @@ -12,21 +12,21 @@ AnimationNodeTimeScale **Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A time-scaling animation node to be used with :ref:`AnimationTree`. +A time-scaling animation node used in :ref:`AnimationTree`. .. rst-class:: classref-introduction-group Description ----------- -Allows scaling the speed of the animation (or reversing it) in any children nodes. Setting it to 0 will pause the animation. +Allows to scale the speed of the animation (or reverse it) in any children :ref:`AnimationNode`\ s. Setting it to ``0.0`` will pause the animation. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `3D Platformer Demo `__ diff --git a/classes/class_animationnodetimeseek.rst b/classes/class_animationnodetimeseek.rst index 3d0a1e37c..bbe1985c1 100644 --- a/classes/class_animationnodetimeseek.rst +++ b/classes/class_animationnodetimeseek.rst @@ -12,7 +12,7 @@ AnimationNodeTimeSeek **Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A time-seeking animation node to be used with :ref:`AnimationTree`. +A time-seeking animation node used in :ref:`AnimationTree`. .. rst-class:: classref-introduction-group @@ -53,7 +53,7 @@ After setting the time and changing the animation playback, the time seek node a Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |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_animationnodetransition.rst b/classes/class_animationnodetransition.rst index 7e6677721..e089dc2f2 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -12,7 +12,7 @@ AnimationNodeTransition **Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A generic animation transition node for :ref:`AnimationTree`. +A transition within an :ref:`AnimationTree` connecting two :ref:`AnimationNode`\ s. .. rst-class:: classref-introduction-group @@ -63,7 +63,7 @@ After setting the request and changing the animation playback, the transition no Tutorials --------- -- :doc:`AnimationTree <../tutorials/animation/animation_tree>` +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` - `3D Platformer Demo `__ diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index 96a961144..8589b52fb 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -12,20 +12,20 @@ AnimationPlayer **Inherits:** :ref:`Node` **<** :ref:`Object` -Player of :ref:`Animation` resources. +A node used for animation playback. .. rst-class:: classref-introduction-group Description ----------- -An animation player is used for general-purpose playback of :ref:`Animation` resources. It contains a dictionary of :ref:`AnimationLibrary` resources and custom blend times between animation transitions. +An animation player is used for general-purpose playback of animations. It contains a dictionary of :ref:`AnimationLibrary` resources and custom blend times between animation transitions. Some methods and properties use a single key to reference an animation directly. These keys are formatted as the key for the library, followed by a forward slash, then the key for the animation within the library, for example ``"movement/run"``. If the library's key is an empty string (known as the default library), the forward slash is omitted, being the same key used by the library. -\ **AnimationPlayer** is more suited than :ref:`Tween` for animations where you know the final values in advance. For example, fading a screen in and out is more easily done with an **AnimationPlayer** node thanks to the animation tools provided by the editor. That particular example can also be implemented with a :ref:`Tween`, but it requires doing everything by code. +\ **AnimationPlayer** is better-suited than :ref:`Tween` for more complex animations, for example ones with non-trivial timings. It can also be used over :ref:`Tween` if the animation track editor is more convenient than doing it in code. -Updating the target properties of animations occurs at process time. +Updating the target properties of animations occurs at the process frame. .. rst-class:: classref-introduction-group @@ -676,6 +676,8 @@ Returns the :ref:`Animation` with the key ``name``. If the anim Returns the first :ref:`AnimationLibrary` with key ``name`` or ``null`` if not found. +To get the **AnimationPlayer**'s global animation library, use ``get_animation_library("")``. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_animationrootnode.rst b/classes/class_animationrootnode.rst index 858275a12..6815cfd87 100644 --- a/classes/class_animationrootnode.rst +++ b/classes/class_animationrootnode.rst @@ -14,7 +14,21 @@ AnimationRootNode **Inherited By:** :ref:`AnimationNodeAnimation`, :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeBlendTree`, :ref:`AnimationNodeStateMachine` -The :ref:`AnimationNode` which can be set as the root of an :ref:`AnimationTree`. +Base class for :ref:`AnimationNode`\ s that hold one or multiple composite animations. Usually used for :ref:`AnimationTree.tree_root`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**AnimationRootNode** is a base class for :ref:`AnimationNode`\ s that hold a complete animation. A complete animation refers to the output of an :ref:`AnimationNodeOutput` in an :ref:`AnimationNodeBlendTree` or the output of another **AnimationRootNode**. Used for :ref:`AnimationTree.tree_root` or in other **AnimationRootNode**\ s. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_animationtree.rst b/classes/class_animationtree.rst index 0762bdf14..d4a6396c5 100644 --- a/classes/class_animationtree.rst +++ b/classes/class_animationtree.rst @@ -12,14 +12,14 @@ AnimationTree **Inherits:** :ref:`Node` **<** :ref:`Object` -A node to be used for advanced animation transitions in an :ref:`AnimationPlayer`. +A node used for advanced animation transitions in an :ref:`AnimationPlayer`. .. rst-class:: classref-introduction-group Description ----------- -A node to be used for advanced animation transitions in an :ref:`AnimationPlayer`. +A node used for advanced animation transitions in an :ref:`AnimationPlayer`. \ **Note:** When linked with an :ref:`AnimationPlayer`, several properties and methods of the corresponding :ref:`AnimationPlayer` will not function as expected. Playback and transitions should be handled using only the **AnimationTree** and its constituent :ref:`AnimationNode`\ (s). The :ref:`AnimationPlayer` node should be used solely for adding, deleting, and editing animations. diff --git a/classes/class_array.rst b/classes/class_array.rst index 57ef5bf49..da69152aa 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -10,14 +10,14 @@ Array ===== -A generic array datatype. +A built-in data structure that holds a sequence of elements. .. rst-class:: classref-introduction-group Description ----------- -A generic array that can contain several elements of any type, accessible by a numerical index starting at 0. Negative indices can be used to count from the back, like in Python (-1 is the last element, -2 is the second to last, etc.). +An array data structure that can contain a sequence of elements of any type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.). \ **Example:**\ @@ -64,8 +64,6 @@ Arrays can be concatenated using the ``+`` operator: -\ **Note:** Concatenating with the ``+=`` operator will create a new array, which has a cost. If you want to append another array to an existing array, :ref:`append_array` is more efficient. - \ **Note:** Arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate`. \ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. diff --git a/classes/class_aspectratiocontainer.rst b/classes/class_aspectratiocontainer.rst index 59ffe9b9f..e635f99fc 100644 --- a/classes/class_aspectratiocontainer.rst +++ b/classes/class_aspectratiocontainer.rst @@ -12,21 +12,21 @@ AspectRatioContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Container that preserves its child controls' aspect ratio. +A container that preserves the proportions of its child controls. .. rst-class:: classref-introduction-group Description ----------- -Arranges child controls in a way to preserve their aspect ratio automatically whenever the container is resized. Solves the problem where the container size is dynamic and the contents' size needs to adjust accordingly without losing proportions. +A container type that arranges its child controls in a way that preserves their proportions automatically when the container is resized. Useful when a container has a dynamic size and the child nodes must adjust their sizes accordingly without losing their aspect ratios. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_audiostreamplaybackpolyphonic.rst b/classes/class_audiostreamplaybackpolyphonic.rst index 40b3090be..257644fec 100644 --- a/classes/class_audiostreamplaybackpolyphonic.rst +++ b/classes/class_audiostreamplaybackpolyphonic.rst @@ -87,7 +87,7 @@ Return true whether the stream associated with an integer ID is still playing. C Play an :ref:`AudioStream` at a given offset, volume and pitch scale. Playback starts immediately. -The return value is an unique integer ID that is associated to this playback stream and which can be used to control it. +The return value is a unique integer ID that is associated to this playback stream and which can be used to control it. This ID becomes invalid when the stream ends (if it does not loop), when the **AudioStreamPlaybackPolyphonic** is stopped, or when :ref:`stop_stream` is called. diff --git a/classes/class_basebutton.rst b/classes/class_basebutton.rst index 63973222c..6facd2873 100644 --- a/classes/class_basebutton.rst +++ b/classes/class_basebutton.rst @@ -14,14 +14,14 @@ BaseButton **Inherited By:** :ref:`Button`, :ref:`LinkButton`, :ref:`TextureButton` -Base class for different kinds of buttons. +Abstract base class for GUI buttons. .. rst-class:: classref-introduction-group Description ----------- -BaseButton is the abstract base class for buttons, so it shouldn't be used directly (it doesn't display anything). Other types of buttons inherit from it. +**BaseButton** is an abstract base class for GUI buttons. It doesn't display anything by itself. .. rst-class:: classref-reftable-group @@ -250,6 +250,8 @@ Determines when the button is considered clicked, one of the :ref:`ActionMode` associated with the button. Not to be confused with node groups. +\ **Note:** The button will be configured as a radio button if a :ref:`ButtonGroup` is assigned to it. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_basis.rst b/classes/class_basis.rst index 738238701..d895a369c 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -10,18 +10,18 @@ Basis ===== -3×3 matrix datatype. +A 3×3 matrix for representing 3D rotation and scale. .. rst-class:: classref-introduction-group Description ----------- -3×3 matrix used for 3D rotation and scale. Almost always used as an orthogonal basis for a :ref:`Transform3D`. +A 3×3 matrix used for representing 3D rotation and scale. Usually used as an orthogonal basis for a :ref:`Transform3D`. Contains 3 vector fields X, Y and Z as its columns, which are typically interpreted as the local basis vectors of a transformation. For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S). -Can also be accessed as array of 3D vectors. These vectors are normally orthogonal to each other, but are not necessarily normalized (due to scaling). +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. @@ -394,7 +394,7 @@ Returns the inverse of the matrix. :ref:`bool` **is_equal_approx** **(** :ref:`Basis` b **)** |const| -Returns ``true`` if this basis and ``b`` are approximately equal, by calling ``is_equal_approx`` on each component. +Returns ``true`` if this basis and ``b`` are approximately equal, by calling :ref:`@GlobalScope.is_equal_approx` on all vector components. .. rst-class:: classref-item-separator @@ -406,7 +406,7 @@ Returns ``true`` if this basis and ``b`` are approximately equal, by calling ``i :ref:`bool` **is_finite** **(** **)** |const| -Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite` on each component. +Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite` on all vector components. .. rst-class:: classref-item-separator diff --git a/classes/class_bone2d.rst b/classes/class_bone2d.rst index 213233f58..dd499cc3a 100644 --- a/classes/class_bone2d.rst +++ b/classes/class_bone2d.rst @@ -12,16 +12,16 @@ Bone2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Joint used with :ref:`Skeleton2D` to control and animate other nodes. +A joint used with :ref:`Skeleton2D` to control and animate other nodes. .. rst-class:: classref-introduction-group Description ----------- -Use a hierarchy of ``Bone2D`` bound to a :ref:`Skeleton2D` to control, and animate other :ref:`Node2D` nodes. +A hierarchy of **Bone2D**\ s can be bound to a :ref:`Skeleton2D` to control and animate other :ref:`Node2D` nodes. -You can use ``Bone2D`` and ``Skeleton2D`` nodes to animate 2D meshes created with the Polygon 2D UV editor. +You can use **Bone2D** and :ref:`Skeleton2D` nodes to animate 2D meshes created with the :ref:`Polygon2D` UV editor. Each bone has a :ref:`rest` transform that you can reset to with :ref:`apply_rest`. These rest poses are relative to the bone's parent. @@ -116,7 +116,7 @@ Stores the node's current transforms in :ref:`rest`. :ref:`bool` **get_autocalculate_length_and_angle** **(** **)** |const| -Returns whether this ``Bone2D`` node is going to autocalculate its length and bone angle using its first ``Bone2D`` child node, if one exists. If there are no ``Bone2D`` children, then it cannot autocalculate these values and will print a warning. +Returns whether this **Bone2D** is going to autocalculate its length and bone angle using its first **Bone2D** child node, if one exists. If there are no **Bone2D** children, then it cannot autocalculate these values and will print a warning. .. rst-class:: classref-item-separator @@ -128,9 +128,9 @@ Returns whether this ``Bone2D`` node is going to autocalculate its length and bo :ref:`float` **get_bone_angle** **(** **)** |const| -Returns the angle of the bone in the ``Bone2D`` node. +Returns the angle of the bone in the **Bone2D**. -\ **Note:** This is different from the ``Bone2D``'s rotation. The bone angle is the rotation of the bone shown by the ``Bone2D`` gizmo, and because ``Bone2D`` bones are based on positions, this can vary from the actual rotation of the ``Bone2D`` node. +\ **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s :ref:`Node2D.transform`. .. rst-class:: classref-item-separator @@ -154,7 +154,7 @@ Returns the node's index as part of the entire skeleton. See :ref:`Skeleton2D` **get_length** **(** **)** |const| -Returns the length of the bone in the ``Bone2D`` node. +Returns the length of the bone in the **Bone2D** node. .. rst-class:: classref-item-separator @@ -178,7 +178,7 @@ Returns the node's :ref:`rest` ``Transform2D`` if it void **set_autocalculate_length_and_angle** **(** :ref:`bool` auto_calculate **)** -When set to ``true``, the ``Bone2D`` node will attempt to automatically calculate the bone angle and length using the first child ``Bone2D`` node, if one exists. If none exist, the ``Bone2D`` cannot automatically calculate these values and will print a warning. +When set to ``true``, the **Bone2D** node will attempt to automatically calculate the bone angle and length using the first child **Bone2D** node, if one exists. If none exist, the **Bone2D** cannot automatically calculate these values and will print a warning. .. rst-class:: classref-item-separator @@ -190,9 +190,9 @@ When set to ``true``, the ``Bone2D`` node will attempt to automatically calculat void **set_bone_angle** **(** :ref:`float` angle **)** -Sets the bone angle for the ``Bone2D`` node. This is typically set to the rotation from the ``Bone2D`` node to a child ``Bone2D`` node. +Sets the bone angle for the **Bone2D**. This is typically set to the rotation from the **Bone2D** to a child **Bone2D** node. -\ **Note:** This is different from the ``Bone2D``'s rotation. The bone angle is the rotation of the bone shown by the ``Bone2D`` gizmo, and because ``Bone2D`` bones are based on positions, this can vary from the actual rotation of the ``Bone2D`` node. +\ **Note:** **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s :ref:`Node2D.transform`. .. rst-class:: classref-item-separator @@ -204,7 +204,7 @@ Sets the bone angle for the ``Bone2D`` node. This is typically set to the rotati void **set_length** **(** :ref:`float` length **)** -Sets the length of the bone in the ``Bone2D`` node. +Sets the length of the bone in the **Bone2D**. .. |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_boneattachment3d.rst b/classes/class_boneattachment3d.rst index fde33cf6c..e6da28a4b 100644 --- a/classes/class_boneattachment3d.rst +++ b/classes/class_boneattachment3d.rst @@ -12,16 +12,14 @@ BoneAttachment3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -A node that will attach to a bone. +А node that dynamically copies or overrides the 3D transform of a bone in its parent :ref:`Skeleton3D`. .. rst-class:: classref-introduction-group Description ----------- -This node will allow you to select a bone for this node to attach to. The BoneAttachment3D node can copy the transform of the select bone, or can override the transform of the selected bone. - -The BoneAttachment3D node must either be a child of a :ref:`Skeleton3D` node or be given an external :ref:`Skeleton3D` to use in order to function properly. +This node selects a bone in a :ref:`Skeleton3D` and attaches to it. This means that the **BoneAttachment3D** node will either dynamically copy or override the 3D transform of the selected bone. .. rst-class:: classref-reftable-group diff --git a/classes/class_bonemap.rst b/classes/class_bonemap.rst index c4a99db19..183d6cd1c 100644 --- a/classes/class_bonemap.rst +++ b/classes/class_bonemap.rst @@ -12,14 +12,14 @@ BoneMap **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Bone map for retargeting. +Describes a mapping of bone names for retargeting :ref:`Skeleton3D` into common names defined by a :ref:`SkeletonProfile`. .. rst-class:: classref-introduction-group Description ----------- -This class contains a hashmap that uses a list of bone names in :ref:`SkeletonProfile` as key names. +This class contains a dictionary that uses a list of bone names in :ref:`SkeletonProfile` as key names. By assigning the actual :ref:`Skeleton3D` bone name as the key value, it maps the :ref:`Skeleton3D` to the :ref:`SkeletonProfile`. diff --git a/classes/class_bool.rst b/classes/class_bool.rst index 4b075127d..8c19cc834 100644 --- a/classes/class_bool.rst +++ b/classes/class_bool.rst @@ -10,113 +10,59 @@ bool ==== -Boolean built-in type. +A built-in boolean type. .. rst-class:: classref-introduction-group Description ----------- -Boolean is a built-in type. There are two boolean values: ``true`` and ``false``. You can think of it as a switch with on or off (1 or 0) setting. Booleans are used in programming for logic in condition statements, like ``if`` statements. +A **bool** is always one of two values: ``true`` or ``false``, similar to a switch that is either on or off. Booleans are used in programming for logic in condition statements. -Booleans can be directly used in ``if`` statements. The code below demonstrates this on the ``if can_shoot:`` line. You don't need to use ``== true``, you only need ``if can_shoot:``. Similarly, use ``if not can_shoot:`` rather than ``== false``. +Booleans can be directly used in ``if`` and ``elif`` statements. You don't need to add ``== true`` or ``== false``: .. tabs:: .. code-tab:: gdscript - var _can_shoot = true - - func shoot(): - if _can_shoot: - pass # Perform shooting actions here. + if can_shoot: + launch_bullet() .. code-tab:: csharp - private bool _canShoot = true; - - public void Shoot() + if (canShoot) { - if (_canShoot) - { - // Perform shooting actions here. - } + launchBullet(); } -The following code will only create a bullet if both conditions are met: action "shoot" is pressed and if ``can_shoot`` is ``true``. +Many common methods and operations return **bool**\ s, for example, ``shooting_cooldown <= 0.0`` may evaluate to ``true`` or ``false`` depending on the number's value. -\ **Note:** ``Input.is_action_pressed("shoot")`` is also a boolean that is ``true`` when "shoot" is pressed and ``false`` when "shoot" isn't pressed. +\ **bool**\ s are usually used with the logical operators ``and``, ``or``, and ``not`` to create complex conditions: .. tabs:: .. code-tab:: gdscript - var _can_shoot = true + if bullets > 0 and not is_reloading: + launch_bullet() - func shoot(): - if _can_shoot and Input.is_action_pressed("shoot"): - create_bullet() + if bullets == 0 or is_reloading: + play_clack_sound() .. code-tab:: csharp - private bool _canShoot = true; - - public void Shoot() + if (bullets > 0 && !isReloading) { - if (_canShoot && Input.IsActionPressed("shoot")) - { - CreateBullet(); - } - } - - - -The following code will set ``can_shoot`` to ``false`` and start a timer. This will prevent player from shooting until the timer runs out. Next ``can_shoot`` will be set to ``true`` again allowing player to shoot once again. - - -.. tabs:: - - .. code-tab:: gdscript - - var _can_shoot = true - @onready var _cool_down = $CoolDownTimer - - func shoot(): - if _can_shoot and Input.is_action_pressed("shoot"): - create_bullet() - _can_shoot = false - _cool_down.start() - - func _on_cool_down_timer_timeout(): - _can_shoot = true - - .. code-tab:: csharp - - private bool _canShoot = true; - private Timer _coolDown; - - public override void _Ready() - { - _coolDown = GetNode("CoolDownTimer"); + launchBullet(); } - public void Shoot() + if (bullets == 0 || isReloading) { - if (_canShoot && Input.IsActionPressed("shoot")) - { - CreateBullet(); - _canShoot = false; - _coolDown.Start(); - } - } - - public void OnCoolDownTimerTimeout() - { - _canShoot = true; + playClackSound(); } @@ -192,7 +138,7 @@ Constructs a **bool** as a copy of the given **bool**. :ref:`bool` **bool** **(** :ref:`float` from **)** -Cast a :ref:`float` value to a boolean value, this method will return ``false`` if ``0.0`` is passed in, and ``true`` for all other floats. +Cast a :ref:`float` value to a boolean value. This method will return ``false`` if ``0.0`` is passed in, and ``true`` for all other values. .. rst-class:: classref-item-separator @@ -202,7 +148,7 @@ Cast a :ref:`float` value to a boolean value, this method will retu :ref:`bool` **bool** **(** :ref:`int` from **)** -Cast an :ref:`int` value to a boolean value, this method will return ``false`` if ``0`` is passed in, and ``true`` for all other ints. +Cast an :ref:`int` value to a boolean value. This method will return ``false`` if ``0`` is passed in, and ``true`` for all other values. .. rst-class:: classref-section-separator diff --git a/classes/class_boxcontainer.rst b/classes/class_boxcontainer.rst index 0ff1347f1..983d39054 100644 --- a/classes/class_boxcontainer.rst +++ b/classes/class_boxcontainer.rst @@ -14,21 +14,21 @@ BoxContainer **Inherited By:** :ref:`HBoxContainer`, :ref:`VBoxContainer` -Base class for box containers. +A container that arranges its child controls horizontally or vertically. .. rst-class:: classref-introduction-group Description ----------- -Arranges child :ref:`Control` nodes vertically or horizontally, and rearranges them automatically when their minimum size changes. +A container that arranges its child controls horizontally or vertically, rearranging them automatically when their minimum size changes. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_button.rst b/classes/class_button.rst index cfe69a10f..509459638 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -14,14 +14,14 @@ Button **Inherited By:** :ref:`CheckBox`, :ref:`CheckButton`, :ref:`ColorPickerButton`, :ref:`MenuButton`, :ref:`OptionButton` -Standard themed Button. +A themed button that can contain text and an icon. .. rst-class:: classref-introduction-group Description ----------- -Button is the standard themed button. It can contain text and an icon, and will display them according to the current :ref:`Theme`. +**Button** is the standard themed button. It can contain text and an icon, and it will display them according to the current :ref:`Theme`. \ **Example of creating a button and assigning an action when pressed by code:**\ @@ -56,11 +56,9 @@ Button is the standard themed button. It can contain text and an icon, and will -Buttons (like all Control nodes) can also be created in the editor, but some situations may require creating them from code. - See also :ref:`BaseButton` which contains common properties and methods associated with this node. -\ **Note:** Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions, as :ref:`TouchScreenButton` supports multitouch. +\ **Note:** Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions. .. rst-class:: classref-introduction-group diff --git a/classes/class_buttongroup.rst b/classes/class_buttongroup.rst index f30f5b659..2ccfa12d4 100644 --- a/classes/class_buttongroup.rst +++ b/classes/class_buttongroup.rst @@ -12,16 +12,16 @@ ButtonGroup **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Group of Buttons. +A group of buttons that doesn't allow more than one button to be pressed at a time. .. rst-class:: classref-introduction-group Description ----------- -Group of :ref:`BaseButton`. The members of this group are treated like radio buttons in the sense that only one button can be pressed at the same time. +A group of :ref:`BaseButton`-derived buttons. The buttons in a **ButtonGroup** are treated like radio buttons: No more than one button can be pressed at a time. Some types of buttons (such as :ref:`CheckBox`) may have a special appearance in this state. -Every member of the ButtonGroup should have :ref:`BaseButton.toggle_mode` set to ``true``. +Every member of a **ButtonGroup** should have :ref:`BaseButton.toggle_mode` set to ``true``. .. rst-class:: classref-reftable-group diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 9d8c0f800..03d4f8a78 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -10,7 +10,7 @@ Callable ======== -Built-in type representing a method in an object instance or a standalone function. +A built-in type representing a method or a standalone function. .. rst-class:: classref-introduction-group diff --git a/classes/class_camera3d.rst b/classes/class_camera3d.rst index 6adb5d6f9..3a29f1a8e 100644 --- a/classes/class_camera3d.rst +++ b/classes/class_camera3d.rst @@ -250,7 +250,13 @@ The :ref:`CameraAttributes` to use for this camera. - void **set_cull_mask** **(** :ref:`int` value **)** - :ref:`int` **get_cull_mask** **(** **)** -The culling mask that describes which 3D render layers are rendered by this camera. +The culling mask that describes which :ref:`VisualInstance3D.layers` are rendered by this camera. By default, all 20 user-visible layers are rendered. + +\ **Note:** Since the :ref:`cull_mask` allows for 32 layers to be stored in total, there are an additional 12 layers that are only used internally by the engine and aren't exposed in the editor. Setting :ref:`cull_mask` using a script allows you to toggle those reserved layers, which can be useful for editor plugins. + +To adjust :ref:`cull_mask` more easily using a script, use :ref:`get_cull_mask_value` and :ref:`set_cull_mask_value`. + +\ **Note:** :ref:`VoxelGI`, SDFGI and :ref:`LightmapGI` will always take all layers into account to determine what contributes to global illumination. If this is an issue, set :ref:`GeometryInstance3D.gi_mode` to :ref:`GeometryInstance3D.GI_MODE_DISABLED` for meshes and :ref:`Light3D.light_bake_mode` to :ref:`Light3D.BAKE_DISABLED` for lights to exclude them from global illumination. .. rst-class:: classref-item-separator @@ -320,7 +326,7 @@ The :ref:`Environment` to use for this camera. - void **set_far** **(** :ref:`float` value **)** - :ref:`float` **get_far** **(** **)** -The distance to the far culling boundary for this camera relative to its local Z axis. +The distance to the far culling boundary for this camera relative to its local Z axis. Higher values allow the camera to see further away, while decreasing :ref:`far` can improve performance if it results in objects being partially or fully culled. .. rst-class:: classref-item-separator @@ -417,7 +423,7 @@ The axis to lock during :ref:`fov`/:ref:`size` value **)** - :ref:`float` **get_near** **(** **)** -The distance to the near culling boundary for this camera relative to its local Z axis. +The distance to the near culling boundary for this camera relative to its local Z axis. Lower values allow the camera to see objects more up close to its origin, at the cost of lower precision across the *entire* range. Values lower than the default can lead to increased Z-fighting. .. rst-class:: classref-item-separator diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index 28de536c9..4637b8427 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -14,24 +14,20 @@ CanvasItem **Inherited By:** :ref:`Control`, :ref:`Node2D` -Base class of anything 2D. +Abstract base class for everything in 2D space. .. rst-class:: classref-introduction-group Description ----------- -Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. **CanvasItem** is extended by :ref:`Control` for anything GUI-related, and by :ref:`Node2D` for anything related to the 2D engine. +Abstract base class for everything in 2D space. Canvas items are laid out in a tree; children inherit and extend their parent's transform. **CanvasItem** is extended by :ref:`Control` for GUI-related nodes, and by :ref:`Node2D` for 2D game objects. -Any **CanvasItem** can draw. For this, :ref:`queue_redraw` is called by the engine, then :ref:`NOTIFICATION_DRAW` will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the **CanvasItem** are provided (see ``draw_*`` functions). However, they can only be used inside :ref:`_draw`, its corresponding :ref:`Object._notification` or methods connected to the :ref:`draw` signal. +Any **CanvasItem** can draw. For this, :ref:`queue_redraw` is called by the engine, then :ref:`NOTIFICATION_DRAW` will be received on idle time to request a redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the **CanvasItem** are provided (see ``draw_*`` functions). However, they can only be used inside :ref:`_draw`, its corresponding :ref:`Object._notification` or methods connected to the :ref:`draw` signal. -Canvas items are drawn in tree order. By default, children are on top of their parents so a root **CanvasItem** will be drawn behind everything. This behavior can be changed on a per-item basis. +Canvas items are drawn in tree order. By default, children are on top of their parents, so a root **CanvasItem** will be drawn behind everything. This behavior can be changed on a per-item basis. -A **CanvasItem** can also be hidden, which will also hide its children. It provides many ways to change parameters such as modulation (for itself and its children) and self modulation (only for itself), as well as its blend mode. - -Ultimately, a transform notification can be requested, which will notify the node that its global position changed in case the parent tree changed. - -\ **Note:** Unless otherwise specified, all methods that have angle parameters must have angles specified as *radians*. To convert degrees to radians, use :ref:`@GlobalScope.deg_to_rad`. +A **CanvasItem** can be hidden, which will also hide its children. By adjusting various other properties of a **CanvasItem**, you can also modulate its color (via :ref:`modulate` or :ref:`self_modulate`), change its Z-index, blend mode, and more. .. rst-class:: classref-introduction-group diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index 1123f59ed..b80d5bf77 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -14,16 +14,18 @@ CanvasLayer **Inherited By:** :ref:`ParallaxBackground` -Canvas drawing layer. +A node used for independent rendering of objects within a 2D scene. .. rst-class:: classref-introduction-group Description ----------- -Canvas drawing layer. :ref:`CanvasItem` nodes that are direct or indirect children of a **CanvasLayer** will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index 0, so a **CanvasLayer** with index -1 will be drawn below, and one with index 1 will be drawn above. This is very useful for HUDs (in layer 1+ or above), or backgrounds (in layer -1 or below). +:ref:`CanvasItem`-derived nodes that are direct or indirect children of a **CanvasLayer** will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index ``0``, so a **CanvasLayer** with index ``-1`` will be drawn below, and a **CanvasLayer** with index ``1`` will be drawn above. This order will hold regardless of the :ref:`CanvasItem.z_index` of the nodes within each layer. -Embedded :ref:`Window`\ s are placed in layer 1024. CanvasItems in layer 1025 or above appear in front of embedded windows, CanvasItems in layer 1023 or below appear behind embedded windows. +\ **CanvasLayer**\ s can be hidden and they can also optionally follow the viewport. This makes them useful for HUDs like health bar overlays (on layers ``1`` and higher) or backgrounds (on layers ``-1`` and lower). + +\ **Note:** Embedded :ref:`Window`\ s are placed on layer ``1024``. :ref:`CanvasItem`\ s on layers ``1025`` and higher appear in front of embedded windows. .. rst-class:: classref-introduction-group diff --git a/classes/class_canvasmodulate.rst b/classes/class_canvasmodulate.rst index 8bc17a6e1..2cd649741 100644 --- a/classes/class_canvasmodulate.rst +++ b/classes/class_canvasmodulate.rst @@ -12,14 +12,14 @@ CanvasModulate **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tint the entire canvas. +A node that applies a color tint to a canvas. .. rst-class:: classref-introduction-group Description ----------- -**CanvasModulate** tints the canvas elements using its assigned :ref:`color`. +**CanvasModulate** applies a color tint to all nodes on a canvas. Only one can be used to tint a canvas, but :ref:`CanvasLayer`\ s can be used to render things independently. .. rst-class:: classref-reftable-group diff --git a/classes/class_centercontainer.rst b/classes/class_centercontainer.rst index 8cbab80e0..bfb8f528c 100644 --- a/classes/class_centercontainer.rst +++ b/classes/class_centercontainer.rst @@ -12,21 +12,21 @@ CenterContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Keeps children controls centered. +A container that keeps child controls in its center. .. rst-class:: classref-introduction-group Description ----------- -CenterContainer keeps children controls centered. This container keeps all children to their minimum size, in the center. +**CenterContainer** is a container that keeps all of its child controls in its center at their minimum size. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_checkbox.rst b/classes/class_checkbox.rst index c9f0e06e3..c9d9763be 100644 --- a/classes/class_checkbox.rst +++ b/classes/class_checkbox.rst @@ -12,17 +12,19 @@ CheckBox **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Binary choice user interface widget. See also :ref:`CheckButton`. +A button that represents a binary choice. .. rst-class:: classref-introduction-group Description ----------- -A checkbox allows the user to make a binary choice (choosing only one of two possible options). It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckBox when toggling it has **no** immediate effect on something. For example, it could be used when toggling it will only do something once a confirmation button is pressed. +**CheckBox** allows the user to choose one of only two possible options. It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckBox** when toggling it has **no** immediate effect on something. For example, it could be used when toggling it will only do something once a confirmation button is pressed. See also :ref:`BaseButton` which contains common properties and methods associated with this node. +When :ref:`BaseButton.button_group` specifies a :ref:`ButtonGroup`, **CheckBox** changes its appearance to that of a radio button and uses the various ``radio_*`` theme properties. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_checkbutton.rst b/classes/class_checkbutton.rst index 15d7b76f0..e4000416f 100644 --- a/classes/class_checkbutton.rst +++ b/classes/class_checkbutton.rst @@ -12,14 +12,14 @@ CheckButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Checkable button. See also :ref:`CheckBox`. +A button that represents a binary choice. .. rst-class:: classref-introduction-group Description ----------- -CheckButton is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckButton when toggling it has an **immediate** effect on something. For example, it could be used if toggling it enables/disables a setting without requiring the user to press a confirmation button. +**CheckButton** is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckButton** when toggling it has an **immediate** effect on something. For example, it can be used when pressing it shows or hides advanced settings, without asking the user to confirm this action. See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_classdb.rst b/classes/class_classdb.rst index 6d4c95a62..edf7424c8 100644 --- a/classes/class_classdb.rst +++ b/classes/class_classdb.rst @@ -12,7 +12,7 @@ ClassDB **Inherits:** :ref:`Object` -Class information repository. +A class information repository. .. rst-class:: classref-introduction-group diff --git a/classes/class_codeedit.rst b/classes/class_codeedit.rst index 0715fda60..560fad281 100644 --- a/classes/class_codeedit.rst +++ b/classes/class_codeedit.rst @@ -12,16 +12,16 @@ CodeEdit **Inherits:** :ref:`TextEdit` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Multiline text control intended for editing code. +A multiline text editor designed for editing code. .. rst-class:: classref-introduction-group Description ----------- -CodeEdit is a specialized :ref:`TextEdit` designed for editing plain text code files. It contains a bunch of features commonly found in code editors such as line numbers, line folding, code completion, indent management and string / comment management. +CodeEdit is a specialized :ref:`TextEdit` designed for editing plain text code files. It has many features commonly found in code editors such as line numbers, line folding, code completion, indent management, and string/comment management. -\ **Note:** By default **CodeEdit** always use left-to-right text direction to correctly display source code. +\ **Note:** Regardless of locale, **CodeEdit** will by default always use left-to-right text direction to correctly display source code. .. rst-class:: classref-reftable-group diff --git a/classes/class_codehighlighter.rst b/classes/class_codehighlighter.rst index e70b6cfa6..aef68710d 100644 --- a/classes/class_codehighlighter.rst +++ b/classes/class_codehighlighter.rst @@ -12,14 +12,14 @@ CodeHighlighter **Inherits:** :ref:`SyntaxHighlighter` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A syntax highlighter for code. +A syntax highlighter intended for code. .. rst-class:: classref-introduction-group Description ----------- -A syntax highlighter for code. +By adjusting various properties of this resource, you can change the colors of strings, comments, numbers, and other text patterns inside a :ref:`TextEdit` control. .. rst-class:: classref-reftable-group diff --git a/classes/class_color.rst b/classes/class_color.rst index c789e1be7..ba1f494b5 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -10,18 +10,18 @@ Color ===== -Color built-in type, in RGBA format. +A color represented in RGBA format. .. rst-class:: classref-introduction-group Description ----------- -A color represented in RGBA format by red (:ref:`r`), green (:ref:`g`), blue (:ref:`b`), and alpha (:ref:`a`) components. Each component is a 16-bit floating-point value, usually ranging from 0 to 1. Some properties (such as :ref:`CanvasItem.modulate`) may support values greater than 1, for overbright or High Dynamic Range colors. If you want to supply values in a range of 0 to 255, you should use :ref:`@GDScript.Color8`. +A color represented in RGBA format by a red (:ref:`r`), green (:ref:`g`), blue (:ref:`b`), and alpha (:ref:`a`) component. Each component is a 16-bit floating-point value, usually ranging from ``0.0`` to ``1.0``. Some properties (such as :ref:`CanvasItem.modulate`) may support values greater than ``1.0``, for overbright or HDR (High Dynamic Range) colors. -Colors can also be created by name from a set of standardized colors, through the :ref:`String` constructor, :ref:`from_string`, or by directly fetching the color constants documented here. The standardized color set is based on the `X11 color names `__, with the addition of :ref:`TRANSPARENT`. +Colors can be created in various ways: By the various **Color** constructors, by static methods such as :ref:`from_hsv`, and by using a name from the set of standardized colors based on `X11 color names `__ with the addition of :ref:`TRANSPARENT`. GDScript also provides :ref:`@GDScript.Color8`, which uses integers from ``0`` to ``255`` and doesn't support overbright colors. -\ **Note:** In a boolean context, a Color will evaluate to ``false`` if it's equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. +\ **Note:** In a boolean context, a Color will evaluate to ``false`` if it is equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. \ `Color constants cheatsheet `__ @@ -1791,9 +1791,9 @@ Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclus :ref:`Color` **hex** **(** :ref:`int` hex **)** |static| -Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel, alpha channel first). +Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel). -In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix). +In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRGGBBAA"``). .. tabs:: @@ -1822,9 +1822,9 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima :ref:`Color` **hex64** **(** :ref:`int` hex **)** |static| -Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel, alpha channel first). +Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel). -In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix). +In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRRRGGGGBBBBAAAA"``). .. rst-class:: classref-item-separator diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index 021f5230e..9e4c1d08f 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -12,16 +12,16 @@ ColorPicker **Inherits:** :ref:`VBoxContainer` **<** :ref:`BoxContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Color picker control. +A widget that provides an interface for selecting or modifying a color. .. rst-class:: classref-introduction-group Description ----------- -Displays a color picker widget. Useful for selecting a color from an RGB/RGBA colorspace. +A widget that provides an interface for selecting or modifying a color. It can optionally provide functionalities like a color sampler (eyedropper), color modes, and presets. -\ **Note:** This control is the color picker widget itself. You can use a :ref:`ColorPickerButton` instead if you need a button that brings up a **ColorPicker** in a pop-up. +\ **Note:** This control is the color picker widget itself. You can use a :ref:`ColorPickerButton` instead if you need a button that brings up a **ColorPicker** in a popup. .. rst-class:: classref-introduction-group diff --git a/classes/class_colorpickerbutton.rst b/classes/class_colorpickerbutton.rst index ec82c0d11..f4653cac0 100644 --- a/classes/class_colorpickerbutton.rst +++ b/classes/class_colorpickerbutton.rst @@ -12,14 +12,14 @@ ColorPickerButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Button that pops out a :ref:`ColorPicker`. +A button that brings up a :ref:`ColorPicker` when pressed. .. rst-class:: classref-introduction-group Description ----------- -Encapsulates a :ref:`ColorPicker` making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker` visibility. +Encapsulates a :ref:`ColorPicker`, making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker`'s visibility. See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_colorrect.rst b/classes/class_colorrect.rst index 6f8e902ea..1f7d8ad1c 100644 --- a/classes/class_colorrect.rst +++ b/classes/class_colorrect.rst @@ -12,14 +12,14 @@ ColorRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Colored rectangle. +A control that displays a solid color rectangle. .. rst-class:: classref-introduction-group Description ----------- -Displays a rectangle filled with a solid :ref:`color`. If you need to display the border alone, consider using :ref:`ReferenceRect` instead. +Displays a rectangle filled with a solid :ref:`color`. If you need to display the border alone, consider using a :ref:`Panel` instead. .. rst-class:: classref-introduction-group @@ -60,20 +60,7 @@ Property Descriptions - void **set_color** **(** :ref:`Color` value **)** - :ref:`Color` **get_color** **(** **)** -The fill color. - - -.. tabs:: - - .. code-tab:: gdscript - - $ColorRect.color = Color(1, 0, 0, 1) # Set ColorRect's color to red. - - .. code-tab:: csharp - - GetNode("ColorRect").Color = new Color(1, 0, 0, 1); // Set ColorRect's color to red. - - +The fill color of the rectangle. .. |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_confirmationdialog.rst b/classes/class_confirmationdialog.rst index c16aad078..955676dc6 100644 --- a/classes/class_confirmationdialog.rst +++ b/classes/class_confirmationdialog.rst @@ -14,14 +14,14 @@ ConfirmationDialog **Inherited By:** :ref:`EditorCommandPalette`, :ref:`EditorFileDialog`, :ref:`FileDialog`, :ref:`ScriptCreateDialog` -Dialog for confirmation of actions. +A dialog used for confirmation of actions. .. rst-class:: classref-introduction-group Description ----------- -Dialog for confirmation of actions. This dialog inherits from :ref:`AcceptDialog`, but has by default an OK and Cancel button (in host OS order). +A dialog used for confirmation of actions. This window is similar to :ref:`AcceptDialog`, but pressing its Cancel button can have a different outcome from pressing the OK button. The order of the two buttons varies depending on the host OS. To get cancel action, you can use: diff --git a/classes/class_container.rst b/classes/class_container.rst index 7f9ea8e83..4b7ec84be 100644 --- a/classes/class_container.rst +++ b/classes/class_container.rst @@ -14,23 +14,21 @@ Container **Inherited By:** :ref:`AspectRatioContainer`, :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`FlowContainer`, :ref:`GraphNode`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`SubViewportContainer`, :ref:`TabContainer` -Base node for containers. +Base class for all GUI containers. .. rst-class:: classref-introduction-group Description ----------- -Base node for containers. A **Container** contains other controls and automatically arranges them in a certain way. - -A Control can inherit this to create custom container classes. +Base class for all GUI containers. A **Container** automatically arranges its child controls in a certain way. This class can be inherited to make custom container types. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_control.rst b/classes/class_control.rst index 746f6f2db..bc430bc24 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -14,7 +14,7 @@ Control **Inherited By:** :ref:`BaseButton`, :ref:`ColorRect`, :ref:`Container`, :ref:`GraphEdit`, :ref:`ItemList`, :ref:`Label`, :ref:`LineEdit`, :ref:`MenuBar`, :ref:`NinePatchRect`, :ref:`Panel`, :ref:`Range`, :ref:`ReferenceRect`, :ref:`RichTextLabel`, :ref:`Separator`, :ref:`TabBar`, :ref:`TextEdit`, :ref:`TextureRect`, :ref:`Tree`, :ref:`VideoStreamPlayer` -All user interface nodes inherit from Control. A control's anchors and offsets adapt its position and size relative to its parent. +Base class for all GUI controls. Adapts its position and size based on its parent control. .. rst-class:: classref-introduction-group @@ -1741,7 +1741,7 @@ The size of the node's bounding rectangle, in the node's coordinate system. :ref - void **set_h_size_flags** **(** :ref:`SizeFlags` value **)** - :ref:`SizeFlags` **get_h_size_flags** **(** **)** -Tells the parent :ref:`Container` nodes how they should resize and place the node on the X axis. Use one of the :ref:`SizeFlags` constants to change the flags. See the constants to learn what each does. +Tells the parent :ref:`Container` nodes how they should resize and place the node on the X axis. Use a combination of the :ref:`SizeFlags` constants to change the flags. See the constants to learn what each does. .. rst-class:: classref-item-separator @@ -1775,7 +1775,7 @@ If the node and at least one of its neighbors uses the :ref:`SIZE_EXPAND` value **)** - :ref:`SizeFlags` **get_v_size_flags** **(** **)** -Tells the parent :ref:`Container` nodes how they should resize and place the node on the Y axis. Use one of the :ref:`SizeFlags` constants to change the flags. See the constants to learn what each does. +Tells the parent :ref:`Container` nodes how they should resize and place the node on the Y axis. Use a combination of the :ref:`SizeFlags` constants to change the flags. See the constants to learn what each does. .. rst-class:: classref-item-separator @@ -1896,7 +1896,7 @@ This method should only be used to test the data. Process the data in :ref:`_dro { // Check position if it is relevant to you // Otherwise, just check data - return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().Contains("expected"); + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("expected"); } @@ -1928,7 +1928,7 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`_get_dra public override bool _CanDropData(Vector2 atPosition, Variant data) { - return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().Contains("color"); + return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().ContainsKey("color"); } public override void _DropData(Vector2 atPosition, Variant data) diff --git a/classes/class_crypto.rst b/classes/class_crypto.rst index 6f1b55820..44c78cc6d 100644 --- a/classes/class_crypto.rst +++ b/classes/class_crypto.rst @@ -12,16 +12,16 @@ Crypto **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Access to advanced cryptographic functionalities. +Provides access to advanced cryptographic functionalities. .. rst-class:: classref-introduction-group Description ----------- -The Crypto class allows you to access some more advanced cryptographic functionalities in Godot. +The Crypto class provides access to advanced cryptographic functionalities. -For now, this includes generating cryptographically secure random bytes, RSA keys and self-signed X509 certificates generation, asymmetric key encryption/decryption, and signing/verification. +Currently, this includes asymmetric key encryption/decryption, signing/verification, and generating cryptographically secure random bytes, RSA keys, HMAC digests, and self-signed :ref:`X509Certificate`\ s. .. tabs:: diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 6ed75950c..89e234aa8 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -10,18 +10,16 @@ Dictionary ========== -Dictionary type. +A built-in data structure that holds key-value pairs. .. rst-class:: classref-introduction-group Description ----------- -Dictionary type. Associative container, which contains values referenced by unique keys. Dictionaries are composed of pairs of keys (which must be unique) and values. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is sometimes referred to as a hash map or associative array. +Dictionaries are associative containers that contain values referenced by unique keys. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is often referred to as a hash map or an associative array. -You can define a dictionary by placing a comma-separated list of ``key: value`` pairs in curly braces ``{}``. - -\ **Note:** Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use :ref:`duplicate`. +You can define a dictionary by placing a comma-separated list of ``key: value`` pairs inside curly braces ``{}``. Creating a dictionary: @@ -187,6 +185,8 @@ The keys of a dictionary can be iterated with the ``for`` keyword: +\ **Note:** Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use :ref:`duplicate`. + \ **Note:** Erasing elements while iterating over dictionaries is **not** supported and will result in unpredictable behavior. .. rst-class:: classref-introduction-group @@ -400,9 +400,9 @@ Returns ``true`` if the dictionary contains an entry with the given ``key``. { 210, default }, }; - GD.Print(myDict.Contains("Godot")); // Prints true - GD.Print(myDict.Contains(210)); // Prints true - GD.Print(myDict.Contains(4)); // Prints false + GD.Print(myDict.ContainsKey("Godot")); // Prints true + GD.Print(myDict.ContainsKey(210)); // Prints true + GD.Print(myDict.ContainsKey(4)); // Prints false diff --git a/classes/class_diraccess.rst b/classes/class_diraccess.rst index 4f23556b0..19322411e 100644 --- a/classes/class_diraccess.rst +++ b/classes/class_diraccess.rst @@ -12,14 +12,14 @@ DirAccess **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Type used to handle the filesystem. +Provides methods for managing directories and their content. .. rst-class:: classref-introduction-group Description ----------- -Directory type. It is used to manage directories and their content (not restricted to the project folder). +This class is used to manage directories and their content, even outside of the project folder. \ **DirAccess** can't be instantiated directly. Instead it is created with a static method that takes a path for which it will be opened. @@ -417,7 +417,7 @@ Returns a :ref:`PackedStringArray` containing filenames Affected by :ref:`include_hidden`. -\ **Note:** When used on a ``res://`` path in an exported project, only the files actually included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level ``.godot/`` folder, only paths to ``*.gd`` and ``*.import`` files are returned (plus a few files such as ``project.godot`` or ``project.binary[code] and the project icon). In an exported project, the list of returned files will also vary depending on whether [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true``. +\ **Note:** When used on a ``res://`` path in an exported project, only the files actually included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level ``.godot/`` folder, only paths to ``*.gd`` and ``*.import`` files are returned (plus a few files such as ``project.godot`` or ``project.binary`` and the project icon). In an exported project, the list of returned files will also vary depending on whether :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` is ``true``. .. rst-class:: classref-item-separator diff --git a/classes/class_displayserver.rst b/classes/class_displayserver.rst index d94ba682e..23e51da2f 100644 --- a/classes/class_displayserver.rst +++ b/classes/class_displayserver.rst @@ -12,14 +12,14 @@ DisplayServer **Inherits:** :ref:`Object` -Singleton for window management functions. +A server interface for low-level window management. .. rst-class:: classref-introduction-group Description ----------- -**DisplayServer** handles everything related to window management. This is separated from :ref:`OS` as a single operating system may support multiple display servers. +**DisplayServer** handles everything related to window management. It is separated from :ref:`OS` as a single operating system may support multiple display servers. \ **Headless mode:** Starting the engine with the ``--headless`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>` disables all rendering and window management functions. Most functions from **DisplayServer** will return dummy values in this case. @@ -744,7 +744,7 @@ I-beam cursor shape. This is used by default when hovering a control that accept :ref:`CursorShape` **CURSOR_POINTING_HAND** = ``2`` -Pointing hand cursor shape. This is used by default when hovering a :ref:`LinkButton` or an URL tag in a :ref:`RichTextLabel`. +Pointing hand cursor shape. This is used by default when hovering a :ref:`LinkButton` or a URL tag in a :ref:`RichTextLabel`. .. _class_DisplayServer_constant_CURSOR_CROSS: diff --git a/classes/class_editorfiledialog.rst b/classes/class_editorfiledialog.rst index a6c8781e3..28c07379a 100644 --- a/classes/class_editorfiledialog.rst +++ b/classes/class_editorfiledialog.rst @@ -19,7 +19,7 @@ A modified version of :ref:`FileDialog` used by the editor. Description ----------- -**EditorFileDialog** is an enhanced version of :ref:`FileDialog` available only to editor plugins. Additional features include list of favorited/recent files and ability to see files as thumbnails grid instead of list. +**EditorFileDialog** is an enhanced version of :ref:`FileDialog` available only to editor plugins. Additional features include list of favorited/recent files and the ability to see files as thumbnails grid instead of list. .. rst-class:: classref-reftable-group diff --git a/classes/class_editorimportplugin.rst b/classes/class_editorimportplugin.rst index ea2ef1d6e..664925afc 100644 --- a/classes/class_editorimportplugin.rst +++ b/classes/class_editorimportplugin.rst @@ -51,10 +51,10 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr func _get_preset_count(): return 1 - func _get_preset_name(i): + func _get_preset_name(preset_index): return "Default" - func _get_import_options(i): + func _get_import_options(path, preset_index): return [{"name": "my_option", "default_value": false}] func _import(source_file, save_path, options, platform_variants, gen_files): @@ -115,7 +115,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr new Godot.Collections.Dictionary { { "name", "myOption" }, - { "defaultValue", false }, + { "default_value", false }, } }; } @@ -249,12 +249,12 @@ This method can be overridden to hide specific import options if conditions are .. code-tab:: csharp - public void GetOptionVisibility(string option, Godot.Collections.Dictionary options) + public void _GetOptionVisibility(string option, Godot.Collections.Dictionary options) { // Only show the lossy quality setting if the compression mode is set to "Lossy". - if (option == "compress/lossyQuality" && options.Contains("compress/mode")) + if (option == "compress/lossy_quality" && options.ContainsKey("compress/mode")) { - return (int)options["compress/mode"] == COMPRESS_LOSSY; // This is a constant you set + return (int)options["compress/mode"] == CompressLossy; // This is a constant you set } return true; diff --git a/classes/class_editorinterface.rst b/classes/class_editorinterface.rst index 3f2125180..6a5891810 100644 --- a/classes/class_editorinterface.rst +++ b/classes/class_editorinterface.rst @@ -19,7 +19,7 @@ Godot editor's interface. Description ----------- -EditorInterface gives you control over Godot editor's window. It allows customizing the window, saving and (re-)loading scenes, rendering mesh previews, inspecting and editing resources and objects, and provides access to :ref:`EditorSettings`, :ref:`EditorFileSystem`, :ref:`EditorResourcePreview`, :ref:`ScriptEditor`, the editor viewport, and information about scenes. +**EditorInterface** gives you control over Godot editor's window. It allows customizing the window, saving and (re-)loading scenes, rendering mesh previews, inspecting and editing resources and objects, and provides access to :ref:`EditorSettings`, :ref:`EditorFileSystem`, :ref:`EditorResourcePreview`, :ref:`ScriptEditor`, the editor viewport, and information about scenes. \ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorPlugin.get_editor_interface`. diff --git a/classes/class_editornode3dgizmoplugin.rst b/classes/class_editornode3dgizmoplugin.rst index 8ab7c5ef4..76412506f 100644 --- a/classes/class_editornode3dgizmoplugin.rst +++ b/classes/class_editornode3dgizmoplugin.rst @@ -12,7 +12,7 @@ EditorNode3DGizmoPlugin **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Used by the editor to define Node3D gizmo types. +A class used by the editor to define Node3D gizmo types. .. rst-class:: classref-introduction-group diff --git a/classes/class_editorproperty.rst b/classes/class_editorproperty.rst index 208850047..199d55af8 100644 --- a/classes/class_editorproperty.rst +++ b/classes/class_editorproperty.rst @@ -12,14 +12,14 @@ EditorProperty **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Custom control to edit properties for adding into the inspector. +Custom control for editing properties that can be added to the :ref:`EditorInspector`. .. rst-class:: classref-introduction-group Description ----------- -This control allows property editing for one or multiple properties into :ref:`EditorInspector`. It is added via :ref:`EditorInspectorPlugin`. +A custom control for editing properties that can be added to the :ref:`EditorInspector`. It is added via :ref:`EditorInspectorPlugin`. .. rst-class:: classref-reftable-group diff --git a/classes/class_editorresourcepreview.rst b/classes/class_editorresourcepreview.rst index 335457ec0..92818fada 100644 --- a/classes/class_editorresourcepreview.rst +++ b/classes/class_editorresourcepreview.rst @@ -12,14 +12,14 @@ EditorResourcePreview **Inherits:** :ref:`Node` **<** :ref:`Object` -Helper to generate previews of resources or files. +A node used to generate previews of resources or files. .. rst-class:: classref-introduction-group Description ----------- -This object is used to generate previews for resources of files. +This node is used to generate previews for resources of files. \ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_resource_previewer`. diff --git a/classes/class_editorsettings.rst b/classes/class_editorsettings.rst index c6e82b252..b4951fb12 100644 --- a/classes/class_editorsettings.rst +++ b/classes/class_editorsettings.rst @@ -329,6 +329,8 @@ Properties +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`interface/touchscreen/increase_scrollbar_touch_area` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`interface/touchscreen/scale_gizmo_handles` | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`network/debug/remote_host` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`network/debug/remote_port` | @@ -2331,6 +2333,20 @@ If ``true``, increases the scrollbar touch area to improve usability on touchscr ---- +.. _class_EditorSettings_property_interface/touchscreen/scale_gizmo_handles: + +.. rst-class:: classref-property + +:ref:`float` **interface/touchscreen/scale_gizmo_handles** + +Specify the multiplier to apply to the scale for the editor gizmo handles to improve usability on touchscreen devices. + +\ **Note:** Defaults to ``1`` on non-touchscreen devices. + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorSettings_property_network/debug/remote_host: .. rst-class:: classref-property diff --git a/classes/class_editorsyntaxhighlighter.rst b/classes/class_editorsyntaxhighlighter.rst index 5404011a7..f447d8465 100644 --- a/classes/class_editorsyntaxhighlighter.rst +++ b/classes/class_editorsyntaxhighlighter.rst @@ -12,14 +12,14 @@ EditorSyntaxHighlighter **Inherits:** :ref:`SyntaxHighlighter` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Base Syntax highlighter resource for the :ref:`ScriptEditor`. +Base class for :ref:`SyntaxHighlighter` used by the :ref:`ScriptEditor`. .. rst-class:: classref-introduction-group Description ----------- -Base syntax highlighter resource all editor syntax highlighters extend from, it is used in the :ref:`ScriptEditor`. +Base class that all :ref:`SyntaxHighlighter`\ s used by the :ref:`ScriptEditor` extend from. Add a syntax highlighter to an individual script by calling :ref:`ScriptEditorBase.add_syntax_highlighter`. To apply to all scripts on open, call :ref:`ScriptEditor.register_syntax_highlighter` diff --git a/classes/class_editorvcsinterface.rst b/classes/class_editorvcsinterface.rst index b9e721722..c91fcfc03 100644 --- a/classes/class_editorvcsinterface.rst +++ b/classes/class_editorvcsinterface.rst @@ -265,7 +265,7 @@ Discards the changes made in a file present at ``file_path``. void **_fetch** **(** :ref:`String` remote **)** |virtual| -Fetches new changes from the remote, but doesn't write changes to the current working directory. Equivalent to ``git fetch``. +Fetches new changes from the ``remote``, but doesn't write changes to the current working directory. Equivalent to ``git fetch``. .. rst-class:: classref-item-separator @@ -517,7 +517,7 @@ Helper function to create a commit :ref:`Dictionary` item. ``m :ref:`Dictionary` **create_diff_file** **(** :ref:`String` new_file, :ref:`String` old_file **)** -Helper function to create a ``Dictionary`` for storing old and new diff file paths. +Helper function to create a :ref:`Dictionary` for storing old and new diff file paths. .. rst-class:: classref-item-separator @@ -529,7 +529,7 @@ Helper function to create a ``Dictionary`` for storing old and new diff file pat :ref:`Dictionary` **create_diff_hunk** **(** :ref:`int` old_start, :ref:`int` new_start, :ref:`int` old_lines, :ref:`int` new_lines **)** -Helper function to create a ``Dictionary`` for storing diff hunk data. ``old_start`` is the starting line number in old file. ``new_start`` is the starting line number in new file. ``old_lines`` is the number of lines in the old file. ``new_lines`` is the number of lines in the new file. +Helper function to create a :ref:`Dictionary` for storing diff hunk data. ``old_start`` is the starting line number in old file. ``new_start`` is the starting line number in new file. ``old_lines`` is the number of lines in the old file. ``new_lines`` is the number of lines in the new file. .. rst-class:: classref-item-separator @@ -541,7 +541,7 @@ Helper function to create a ``Dictionary`` for storing diff hunk data. ``old_sta :ref:`Dictionary` **create_diff_line** **(** :ref:`int` new_line_no, :ref:`int` old_line_no, :ref:`String` content, :ref:`String` status **)** -Helper function to create a ``Dictionary`` for storing a line diff. ``new_line_no`` is the line number in the new file (can be ``-1`` if the line is deleted). ``old_line_no`` is the line number in the old file (can be ``-1`` if the line is added). ``content`` is the diff text. ``status`` is a single character string which stores the line origin. +Helper function to create a :ref:`Dictionary` for storing a line diff. ``new_line_no`` is the line number in the new file (can be ``-1`` if the line is deleted). ``old_line_no`` is the line number in the old file (can be ``-1`` if the line is added). ``content`` is the diff text. ``status`` is a single character string which stores the line origin. .. rst-class:: classref-item-separator @@ -553,7 +553,7 @@ Helper function to create a ``Dictionary`` for storing a line diff. ``new_line_n :ref:`Dictionary` **create_status_file** **(** :ref:`String` file_path, :ref:`ChangeType` change_type, :ref:`TreeArea` area **)** -Helper function to create a ``Dictionary`` used by editor to read the status of a file. +Helper function to create a :ref:`Dictionary` used by editor to read the status of a file. .. rst-class:: classref-item-separator diff --git a/classes/class_enetpacketpeer.rst b/classes/class_enetpacketpeer.rst index e5481ad27..40c37b4a4 100644 --- a/classes/class_enetpacketpeer.rst +++ b/classes/class_enetpacketpeer.rst @@ -511,7 +511,7 @@ void **set_timeout** **(** :ref:`int` timeout, :ref:`int` Sets the timeout parameters for a peer. The timeout parameters control how and when a peer will timeout from a failure to acknowledge reliable traffic. Timeout values are expressed in milliseconds. -The ``timeout_limit`` is a factor that, multiplied by a value based on the average round trip time, will determine the timeout limit for a reliable packet. When that limit is reached, the timeout will be doubled, and the peer will be disconnected if that limit has reached ``timeout_min``. The ``timeout_max`` parameter, on the other hand, defines a fixed timeout for which any packet must be acknowledged or the peer will be dropped. +The ``timeout`` is a factor that, multiplied by a value based on the average round trip time, will determine the timeout limit for a reliable packet. When that limit is reached, the timeout will be doubled, and the peer will be disconnected if that limit has reached ``timeout_min``. The ``timeout_max`` parameter, on the other hand, defines a fixed timeout for which any packet must be acknowledged or the peer will be dropped. .. rst-class:: classref-item-separator diff --git a/classes/class_engine.rst b/classes/class_engine.rst index e09ce2653..0260aa0c6 100644 --- a/classes/class_engine.rst +++ b/classes/class_engine.rst @@ -12,7 +12,7 @@ Engine **Inherits:** :ref:`Object` -Access to engine properties. +Provides access to engine properties. .. rst-class:: classref-introduction-group diff --git a/classes/class_fileaccess.rst b/classes/class_fileaccess.rst index abb87235b..8beef6dee 100644 --- a/classes/class_fileaccess.rst +++ b/classes/class_fileaccess.rst @@ -12,14 +12,14 @@ FileAccess **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Type to handle file reading and writing operations. +Provides methods for file reading and writing operations. .. rst-class:: classref-introduction-group Description ----------- -File type. This is used to permanently store data into the user device's file system and to read from it. This can be used to store game save data or player configuration files, for example. +This class can be used to permanently store data in the user device's file system and to read from it. This is useful for store game save data or player configuration files. Here's a sample on how to write and read from a file: @@ -56,24 +56,9 @@ Here's a sample on how to write and read from a file: In the example above, the file will be saved in the user data folder as specified in the :doc:`Data paths <../tutorials/io/data_paths>` documentation. -\ **FileAccess** will close when it's freed, which happens when it goes out of scope or when it gets assigned with ``null``. In C# the reference must be disposed after we are done using it, this can be done with the ``using`` statement or calling the ``Dispose`` method directly. +\ **FileAccess** will close when it's freed, which happens when it goes out of scope or when it gets assigned with ``null``. :ref:`close` can be used to close it before then explicitly. In C# the reference must be disposed manually, which can be done with the ``using`` statement or by calling the ``Dispose`` method directly. - -.. tabs:: - - .. code-tab:: gdscript - - var file = FileAccess.open("res://something") # File is opened and locked for use. - file = null # File is closed. - - .. code-tab:: csharp - - using var file = FileAccess.Open("res://something"); // File is opened and locked for use. - // The using statement calls Dispose when going out of scope. - - - -\ **Note:** To access project resources once exported, it is recommended to use :ref:`ResourceLoader` instead of the **FileAccess** API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. +\ **Note:** To access project resources once exported, it is recommended to use :ref:`ResourceLoader` instead of **FileAccess**, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. \ **Note:** Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing **Alt + F4**). If you stop the project execution by pressing **F8** while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling :ref:`flush` at regular intervals. diff --git a/classes/class_filedialog.rst b/classes/class_filedialog.rst index 386bb8f70..34623d95f 100644 --- a/classes/class_filedialog.rst +++ b/classes/class_filedialog.rst @@ -12,14 +12,14 @@ FileDialog **Inherits:** :ref:`ConfirmationDialog` **<** :ref:`AcceptDialog` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -Dialog for selecting files or directories in the filesystem. +A dialog for selecting files or directories in the filesystem. .. rst-class:: classref-introduction-group Description ----------- -FileDialog is a preset dialog used to choose files and directories in the filesystem. It supports filter masks. The FileDialog automatically sets its window title according to the :ref:`file_mode`. If you want to use a custom title, disable this by setting :ref:`mode_overrides_title` to ``false``. +**FileDialog** is a preset dialog used to choose files and directories in the filesystem. It supports filter masks. **FileDialog** automatically sets its window title according to the :ref:`file_mode`. If you want to use a custom title, disable this by setting :ref:`mode_overrides_title` to ``false``. .. rst-class:: classref-reftable-group diff --git a/classes/class_filesystemdock.rst b/classes/class_filesystemdock.rst index abeb2328a..05876a35b 100644 --- a/classes/class_filesystemdock.rst +++ b/classes/class_filesystemdock.rst @@ -12,7 +12,7 @@ FileSystemDock **Inherits:** :ref:`VBoxContainer` **<** :ref:`BoxContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Editor dock for managing files in the project. +Godot editor's dock for managing files in the project. .. rst-class:: classref-introduction-group @@ -21,7 +21,7 @@ Description This class is available only in :ref:`EditorPlugin`\ s and can't be instantiated. You can access it using :ref:`EditorInterface.get_file_system_dock`. -While FileSystemDock doesn't expose any methods for file manipulation, you can listen for various file-related signals. +While **FileSystemDock** doesn't expose any methods for file manipulation, it can listen for various file-related signals. .. rst-class:: classref-reftable-group diff --git a/classes/class_float.rst b/classes/class_float.rst index 4453d4e61..4c1610b77 100644 --- a/classes/class_float.rst +++ b/classes/class_float.rst @@ -10,18 +10,18 @@ float ===== -Float built-in type. +A built-in type for floating point numbers. .. rst-class:: classref-introduction-group Description ----------- -The **float** built-in type is a 64-bit double-precision floating-point number, equivalent to ``double`` in C++. This type has 14 reliable decimal digits of precision. The **float** type can be stored in :ref:`Variant`, which is the generic type used by the engine. The maximum value of **float** is approximately ``1.79769e308``, and the minimum is approximately ``-1.79769e308``. +The **float** built-in type is a 64-bit double-precision floating-point number, equivalent to ``double`` in C++. This type has 14 reliable decimal digits of precision. The maximum value of **float** is approximately ``1.79769e308``, and the minimum is approximately ``-1.79769e308``. Many methods and properties in the engine use 32-bit single-precision floating-point numbers instead, equivalent to ``float`` in C++, which have 6 reliable decimal digits of precision. For data structures such as :ref:`Vector2` and :ref:`Vector3`, Godot uses 32-bit floating-point numbers by default, but it can be changed to use 64-bit doubles if Godot is compiled with the ``precision=double`` option. -Math done using the **float** type is not guaranteed to be exact or deterministic, and will often result in small errors. You should usually use the :ref:`@GlobalScope.is_equal_approx` and :ref:`@GlobalScope.is_zero_approx` methods instead of ``==`` to compare **float** values for equality. +Math done using the **float** type is not guaranteed to be exact and will often result in small errors. You should usually use the :ref:`@GlobalScope.is_equal_approx` and :ref:`@GlobalScope.is_zero_approx` methods instead of ``==`` to compare **float** values for equality. .. rst-class:: classref-introduction-group @@ -200,6 +200,8 @@ Operator Descriptions Returns ``true`` if two floats are different from each other. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -222,7 +224,7 @@ Returns ``true`` if the integer has different value than the float. :ref:`Color` **operator *** **(** :ref:`Color` right **)** -Multiplies each component of the :ref:`Color` by the given **float**. +Multiplies each component of the :ref:`Color`, including the alpha, by the given **float**. :: @@ -468,6 +470,8 @@ Divides a **float** by an :ref:`int`. The result is a **float**. Returns ``true`` if the left float is less than the right one. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -492,6 +496,8 @@ Returns ``true`` if this **float** is less than the given :ref:`int`. Returns ``true`` if the left float is less than or equal to the right one. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -518,6 +524,8 @@ Returns ``true`` if both floats are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`@GlobalScope.is_equal_approx` or :ref:`@GlobalScope.is_zero_approx` instead, which are more reliable. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -542,6 +550,8 @@ Returns ``true`` if the **float** and the given :ref:`int` are equal. Returns ``true`` if the left float is greater than the right one. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -566,6 +576,8 @@ Returns ``true`` if this **float** is greater than the given :ref:`int` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_flowcontainer.rst b/classes/class_flowcontainer.rst index 111cbdd33..bc6e13a1f 100644 --- a/classes/class_flowcontainer.rst +++ b/classes/class_flowcontainer.rst @@ -14,16 +14,21 @@ FlowContainer **Inherited By:** :ref:`HFlowContainer`, :ref:`VFlowContainer` -Base class for flow containers. +A container that arranges its child controls horizontally or vertically and wraps them around at the borders. .. rst-class:: classref-introduction-group Description ----------- -Arranges child :ref:`Control` nodes vertically or horizontally in a left-to-right or top-to-bottom flow. +A container that arranges its child controls horizontally or vertically and wraps them around at the borders. This is similar to how text in a book wraps around when no more words can fit on a line. -A line is filled with :ref:`Control` nodes until no more fit on the same line, similar to text in an autowrapped label. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_font.rst b/classes/class_font.rst index b4eb9fe39..130fc8267 100644 --- a/classes/class_font.rst +++ b/classes/class_font.rst @@ -14,14 +14,14 @@ Font **Inherited By:** :ref:`FontFile`, :ref:`FontVariation`, :ref:`SystemFont` -Base class for fonts and font variations. +Abstract base class for fonts and font variations. .. rst-class:: classref-introduction-group Description ----------- -Font is the abstract base class for font, so it shouldn't be used directly. Other types of fonts inherit from it. +Abstract base class for different font types. It has methods for drawing text and font character introspection. .. rst-class:: classref-reftable-group diff --git a/classes/class_fontfile.rst b/classes/class_fontfile.rst index f481bd158..5871c6449 100644 --- a/classes/class_fontfile.rst +++ b/classes/class_fontfile.rst @@ -12,7 +12,7 @@ FontFile **Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Font source data and prerendered glyph cache, imported from dynamic or bitmap font. +Holds font source data and prerendered glyph cache, imported from a dynamic or a bitmap font. .. rst-class:: classref-introduction-group @@ -35,9 +35,9 @@ Supported font formats: \ **Note:** A character is a symbol that represents an item (letter, digit etc.) in an abstract way. -\ **Note:** A glyph is a bitmap or shape used to draw one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source. +\ **Note:** A glyph is a bitmap or a shape used to draw one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source. -\ **Note:** If a none of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code. +\ **Note:** If none of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code. .. tabs:: diff --git a/classes/class_fontvariation.rst b/classes/class_fontvariation.rst index c5c6faddc..7de0a27f5 100644 --- a/classes/class_fontvariation.rst +++ b/classes/class_fontvariation.rst @@ -12,14 +12,14 @@ FontVariation **Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Variation of the :ref:`Font`. +A variation of a font with additional settings. .. rst-class:: classref-introduction-group Description ----------- -OpenType variations, simulated bold / slant, and additional font settings like OpenType features and extra spacing. +Provides OpenType variations, simulated bold / slant, and additional font settings like OpenType features and extra spacing. To use simulated bold font variant: diff --git a/classes/class_geometry2d.rst b/classes/class_geometry2d.rst index 9cd809fbd..e1107dc71 100644 --- a/classes/class_geometry2d.rst +++ b/classes/class_geometry2d.rst @@ -12,14 +12,14 @@ Geometry2D **Inherits:** :ref:`Object` -Helper node to calculate generic geometry operations in 2D space. +Provides methods for some common 2D geometric operations. .. rst-class:: classref-introduction-group Description ----------- -Geometry2D provides users with a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations. +Provides a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations in 2D. .. rst-class:: classref-reftable-group diff --git a/classes/class_geometry3d.rst b/classes/class_geometry3d.rst index 27c301c86..a8ddcee97 100644 --- a/classes/class_geometry3d.rst +++ b/classes/class_geometry3d.rst @@ -12,14 +12,14 @@ Geometry3D **Inherits:** :ref:`Object` -Helper node to calculate generic geometry operations in 3D space. +Provides methods for some common 3D geometric operations. .. rst-class:: classref-introduction-group Description ----------- -Geometry3D provides users with a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations. +Provides a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations in 3D. .. rst-class:: classref-reftable-group diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 02bba68cf..feb756114 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -12,18 +12,16 @@ GraphEdit **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -GraphEdit is a control responsible for displaying and manipulating graph-like data using :ref:`GraphNode`\ s. It provides access to creation, removal, connection, and disconnection of nodes. +An editor for graph-like structures, using :ref:`GraphNode`\ s. .. rst-class:: classref-introduction-group Description ----------- -**Note:** Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. +**GraphEdit** provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. -GraphEdit provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. - -GraphEdit by itself is only an empty container, representing an infinite grid where :ref:`GraphNode`\ s can be placed. Each :ref:`GraphNode` represent a node in the graph, a single unit of data in the connected scheme. GraphEdit, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or close a :ref:`GraphNode`, a signal is emitted in the GraphEdit, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. +\ **GraphEdit** by itself is only an empty container, representing an infinite grid where :ref:`GraphNode`\ s can be placed. Each :ref:`GraphNode` represents a node in the graph, a single unit of data in the connected scheme. **GraphEdit**, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or close a :ref:`GraphNode`, a signal is emitted in the **GraphEdit**, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. \ **Performance:** It is greatly advised to enable low-processor usage mode (see :ref:`OS.low_processor_usage_mode`) when using GraphEdits. diff --git a/classes/class_graphnode.rst b/classes/class_graphnode.rst index c81b157ad..5c69150b1 100644 --- a/classes/class_graphnode.rst +++ b/classes/class_graphnode.rst @@ -12,22 +12,20 @@ GraphNode **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -GraphNode is a :ref:`Container` control that represents a single data unit in a :ref:`GraphEdit` graph. You can customize the number, type, and color of left- and right-side connection ports. +A container with connection ports, representing a node in a :ref:`GraphEdit`. .. rst-class:: classref-introduction-group Description ----------- -**Note:** Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. +**GraphNode** allows to create nodes for a :ref:`GraphEdit` graph with customizable content based on its child controls. **GraphNode** is derived from :ref:`Container` and it is responsible for placing its children on screen. This works similar to :ref:`VBoxContainer`. Children, in turn, provide **GraphNode** with so-called slots, each of which can have a connection port on either side. -GraphNode allows to create nodes for a :ref:`GraphEdit` graph with customizable content based on its child :ref:`Control`\ s. GraphNode is a :ref:`Container` and is responsible for placing its children on screen. This works similar to :ref:`VBoxContainer`. Children, in turn, provide GraphNode with so-called slots, each of which can have a connection port on either side. This is similar to how :ref:`TabContainer` uses children to create the tabs. - -Each GraphNode slot is defined by its index and can provide the node with up to two ports: one on the left, and one on the right. By convention the left port is also referred to as the input port and the right port is referred to as the output port. Each port can be enabled and configured individually, using different type and color. The type is an arbitrary value that you can define using your own considerations. The parent :ref:`GraphEdit` will receive this information on each connect and disconnect request. +Each **GraphNode** slot is defined by its index and can provide the node with up to two ports: one on the left, and one on the right. By convention the left port is also referred to as the **input port** and the right port is referred to as the **output port**. Each port can be enabled and configured individually, using different type and color. The type is an arbitrary value that you can define using your own considerations. The parent :ref:`GraphEdit` will receive this information on each connect and disconnect request. Slots can be configured in the Inspector dock once you add at least one child :ref:`Control`. The properties are grouped by each slot's index in the "Slot" section. -\ **Note:** While GraphNode is set up using slots and slot indices, connections are made between the ports which are enabled. Because of that :ref:`GraphEdit` uses port's index and not slot's index. You can use :ref:`get_connection_input_slot` and :ref:`get_connection_output_slot` to get the slot index from the port index. +\ **Note:** While GraphNode is set up using slots and slot indices, connections are made between the ports which are enabled. Because of that, :ref:`GraphEdit` uses the port's index and not the slot's index. You can use :ref:`get_connection_input_slot` and :ref:`get_connection_output_slot` to get the slot index from the port index. .. rst-class:: classref-reftable-group diff --git a/classes/class_gridcontainer.rst b/classes/class_gridcontainer.rst index 78d521f8a..e140e566d 100644 --- a/classes/class_gridcontainer.rst +++ b/classes/class_gridcontainer.rst @@ -12,25 +12,23 @@ GridContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Grid container used to arrange Control-derived children in a grid like layout. +A container that arranges its child controls in a grid layout. .. rst-class:: classref-introduction-group Description ----------- -GridContainer will arrange its Control-derived children in a grid like structure, the grid columns are specified using the :ref:`columns` property and the number of rows will be equal to the number of children in the container divided by the number of columns. For example, if the container has 5 children, and 2 columns, there will be 3 rows in the container. +**GridContainer** arranges its child controls in a grid layout. The number of columns is specified by the :ref:`columns` property, whereas the number of rows depends on how many are needed for the child controls. The number of rows and columns is preserved for every size of the container. -Notice that grid layout will preserve the columns and rows for every size of the container, and that empty columns will be expanded automatically. - -\ **Note:** GridContainer only works with child nodes inheriting from Control. It won't rearrange child nodes inheriting from Node2D. +\ **Note:** **GridContainer** only works with child nodes inheriting from :ref:`Control`. It won't rearrange child nodes inheriting from :ref:`Node2D`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` - `OS Test Demo `__ diff --git a/classes/class_hashingcontext.rst b/classes/class_hashingcontext.rst index dde3cd547..300443938 100644 --- a/classes/class_hashingcontext.rst +++ b/classes/class_hashingcontext.rst @@ -12,14 +12,14 @@ HashingContext **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Context to compute cryptographic hashes over multiple iterations. +Provides functionality for computing cryptographic hashes chunk by chunk. .. rst-class:: classref-introduction-group Description ----------- -The HashingContext class provides an interface for computing cryptographic hashes over multiple iterations. This is useful for example when computing hashes of big files (so you don't have to load them all in memory), network streams, and data streams in general (so you don't have to hold buffers). +The HashingContext class provides an interface for computing cryptographic hashes over multiple iterations. Useful for computing hashes of big files (so you don't have to load them all in memory), network streams, and data streams in general (so you don't have to hold buffers). The :ref:`HashType` enum shows the supported hashing algorithms. diff --git a/classes/class_hboxcontainer.rst b/classes/class_hboxcontainer.rst index 064ef72f0..b193e938c 100644 --- a/classes/class_hboxcontainer.rst +++ b/classes/class_hboxcontainer.rst @@ -14,21 +14,21 @@ HBoxContainer **Inherited By:** :ref:`EditorResourcePicker` -Horizontal box container. +A container that arranges its child controls horizontally. .. rst-class:: classref-introduction-group Description ----------- -Horizontal box container. See :ref:`BoxContainer`. +A variant of :ref:`BoxContainer` that can only arrange its child controls horizontally. Child controls are rearranged automatically when their minimum size changes. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_hflowcontainer.rst b/classes/class_hflowcontainer.rst index b9fd51038..144bcff2d 100644 --- a/classes/class_hflowcontainer.rst +++ b/classes/class_hflowcontainer.rst @@ -12,14 +12,21 @@ HFlowContainer **Inherits:** :ref:`FlowContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal flow container. +A container that arranges its child controls horizontally and wraps them around at the borders. .. rst-class:: classref-introduction-group Description ----------- -Horizontal version of :ref:`FlowContainer`. +A variant of :ref:`FlowContainer` that can only arrange its child controls horizontally, wrapping them around at the borders. This is similar to how text in a book wraps around when no more words can fit on a line. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_hscrollbar.rst b/classes/class_hscrollbar.rst index 0865c05bb..2aaa098b1 100644 --- a/classes/class_hscrollbar.rst +++ b/classes/class_hscrollbar.rst @@ -12,14 +12,14 @@ HScrollBar **Inherits:** :ref:`ScrollBar` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal scroll bar. +A horizontal scrollbar that goes from left (min) to right (max). .. rst-class:: classref-introduction-group Description ----------- -Horizontal version of :ref:`ScrollBar`, which goes from left (min) to right (max). +A horizontal scrollbar, typically used to navigate through content that extends beyond the visible width of a control. It is a :ref:`Range`-based control and goes from left (min) to right (max). .. rst-class:: classref-reftable-group diff --git a/classes/class_hseparator.rst b/classes/class_hseparator.rst index 673dd0ba7..07fdebee6 100644 --- a/classes/class_hseparator.rst +++ b/classes/class_hseparator.rst @@ -12,14 +12,14 @@ HSeparator **Inherits:** :ref:`Separator` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal separator. +A horizontal line used for separating other controls. .. rst-class:: classref-introduction-group Description ----------- -Horizontal separator. See :ref:`Separator`. Even though it looks horizontal, it is used to separate objects vertically. +A horizontal separator used for separating other controls that are arranged **vertically**. **HSeparator** is purely visual and normally drawn as a :ref:`StyleBoxLine`. .. rst-class:: classref-reftable-group diff --git a/classes/class_hslider.rst b/classes/class_hslider.rst index 7e3ad6e3f..25816e7ee 100644 --- a/classes/class_hslider.rst +++ b/classes/class_hslider.rst @@ -12,16 +12,14 @@ HSlider **Inherits:** :ref:`Slider` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal slider. +A horizontal slider that goes from left (min) to right (max). .. rst-class:: classref-introduction-group Description ----------- -Horizontal slider. See :ref:`Slider`. This one goes from left (min) to right (max). - -\ **Note:** The :ref:`Range.changed` and :ref:`Range.value_changed` signals are part of the :ref:`Range` class which this class inherits from. +A horizontal slider, used to adjust a value by moving a grabber along a horizontal axis. It is a :ref:`Range`-based control and goes from left (min) to right (max). .. rst-class:: classref-reftable-group diff --git a/classes/class_hsplitcontainer.rst b/classes/class_hsplitcontainer.rst index 2f90d3bf7..ef02e2c7c 100644 --- a/classes/class_hsplitcontainer.rst +++ b/classes/class_hsplitcontainer.rst @@ -12,21 +12,21 @@ HSplitContainer **Inherits:** :ref:`SplitContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal split container. +A container that splits two child controls horizontally and provides a grabber for adjusting the split ratio. .. rst-class:: classref-introduction-group Description ----------- -Horizontal split container. See :ref:`SplitContainer`. This goes from left to right. +A container that accepts only two child controls, then arranges them horizontally and creates a divisor between them. The divisor can be dragged around to change the size relation between the child controls. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_httpclient.rst b/classes/class_httpclient.rst index 455dfd272..434862a72 100644 --- a/classes/class_httpclient.rst +++ b/classes/class_httpclient.rst @@ -27,7 +27,7 @@ See the :ref:`HTTPRequest` node for a higher-level alternativ A **HTTPClient** should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports Transport Layer Security (TLS), including server certificate verification. HTTP status codes in the 2xx range indicate success, 3xx redirection (i.e. "try again, but over here"), 4xx something was wrong with the request, and 5xx something went wrong on the server's side. -For more information on HTTP, see https://developer.mozilla.org/en-US/docs/Web/HTTP (or read RFC 2616 to get it straight from the source: https://tools.ietf.org/html/rfc2616). +For more information on HTTP, see `MDN's documentation on HTTP `__ (or read `RFC 2616 `__ to get it straight from the source). \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. diff --git a/classes/class_httprequest.rst b/classes/class_httprequest.rst index 194bc3274..22045fa6c 100644 --- a/classes/class_httprequest.rst +++ b/classes/class_httprequest.rst @@ -49,7 +49,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content # Note: Don't make simultaneous requests using a single HTTPRequest node. # The snippet below is provided for reference only. var body = JSON.new().stringify({"name": "Godette"}) - error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body) + error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body) if error != OK: push_error("An error occurred in the HTTP request.") @@ -85,7 +85,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content { { "name", "Godette" } }); - error = httpRequest.Request("https://httpbin.org/post", null, true, HTTPClient.Method.Post, body); + error = httpRequest.Request("https://httpbin.org/post", null, HTTPClient.Method.Post, body); if (error != Error.Ok) { GD.PushError("An error occurred in the HTTP request."); @@ -386,7 +386,7 @@ Request reached its maximum redirect limit, see :ref:`max_redirects` **RESULT_TIMEOUT** = ``13`` - +Request failed due to a timeout. If you expect requests to take a long time, try increasing the value of :ref:`timeout` or setting it to ``0.0`` to remove the timeout completely. .. rst-class:: classref-section-separator @@ -501,7 +501,7 @@ Maximum number of allowed redirects. - void **set_timeout** **(** :ref:`float` value **)** - :ref:`float` **get_timeout** **(** **)** -If set to a value greater than ``0.0`` before the request starts, the HTTP request will time out after ``timeout`` seconds have passed and the request is not *completed* yet. For small HTTP requests such as REST API usage, set :ref:`timeout` to a value between ``10.0`` and ``30.0`` to prevent the application from getting stuck if the request fails to get a response in a timely manner. For file downloads, leave this to ``0.0`` to prevent the download from failing if it takes too much time. +The duration to wait in seconds before a request times out. If :ref:`timeout` is set to ``0.0`` then the request will never time out. For simple requests, such as communication with a REST API, it is recommended that :ref:`timeout` is set to a value suitable for the server response time (e.g. between ``1.0`` and ``10.0``). This will help prevent unwanted timeouts caused by variation in server response times while still allowing the application to detect when a request has timed out. For larger requests such as file downloads it is suggested the :ref:`timeout` be set to ``0.0``, disabling the timeout functionality. This will help to prevent large transfers from failing due to exceeding the timeout value. .. rst-class:: classref-item-separator diff --git a/classes/class_input.rst b/classes/class_input.rst index eff31b74b..470f8b68d 100644 --- a/classes/class_input.rst +++ b/classes/class_input.rst @@ -12,16 +12,16 @@ Input **Inherits:** :ref:`Object` -A singleton that deals with inputs. +A singleton for handling inputs. .. rst-class:: classref-introduction-group Description ----------- -A singleton that deals with inputs. This includes key presses, mouse buttons and movement, joypads, and input actions. Actions and their events can be set in the **Input Map** tab in the **Project > Project Settings**, or with the :ref:`InputMap` class. +The **Input** singleton handles key presses, mouse buttons and movement, gamepads, and input actions. Actions and their events can be set in the **Input Map** tab in **Project > Project Settings**, or with the :ref:`InputMap` class. -\ **Note:** The methods here reflect the global input state and are not affected by :ref:`Control.accept_event` or :ref:`Viewport.set_input_as_handled`, which only deal with the way input is propagated in the :ref:`SceneTree`. +\ **Note:** **Input**'s methods reflect the global input state and are not affected by :ref:`Control.accept_event` or :ref:`Viewport.set_input_as_handled`, as those methods only deal with the way input is propagated in the :ref:`SceneTree`. .. rst-class:: classref-introduction-group @@ -600,7 +600,7 @@ Returns the current value of the joypad axis at given index (see :ref:`JoyAxis` **get_joy_guid** **(** :ref:`int` device **)** |const| -Returns a SDL2-compatible device GUID on platforms that use gamepad remapping. Returns ``"Default Gamepad"`` otherwise. +Returns a SDL2-compatible device GUID on platforms that use gamepad remapping, e.g. ``030000004c050000c405000000010000``. Returns ``"Default Gamepad"`` otherwise. Godot uses the `SDL2 game controller database `__ to determine gamepad names and mappings based on this GUID. .. rst-class:: classref-item-separator @@ -612,7 +612,7 @@ Returns a SDL2-compatible device GUID on platforms that use gamepad remapping. R :ref:`String` **get_joy_name** **(** :ref:`int` device **)** -Returns the name of the joypad at the specified device index. +Returns the name of the joypad at the specified device index, e.g. ``PS4 Controller``. Godot uses the `SDL2 game controller database `__ to determine gamepad names. .. rst-class:: classref-item-separator diff --git a/classes/class_inputevent.rst b/classes/class_inputevent.rst index cd3240e46..ffc474d8e 100644 --- a/classes/class_inputevent.rst +++ b/classes/class_inputevent.rst @@ -14,21 +14,21 @@ InputEvent **Inherited By:** :ref:`InputEventAction`, :ref:`InputEventFromWindow`, :ref:`InputEventJoypadButton`, :ref:`InputEventJoypadMotion`, :ref:`InputEventMIDI`, :ref:`InputEventShortcut` -Generic input event. +Abstract base class for input events. .. rst-class:: classref-introduction-group Description ----------- -Base class of all sort of input event. See :ref:`Node._input`. +Abstract base class of all types of input events. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` - :doc:`Viewport and canvas transforms <../tutorials/2d/2d_transforms>` diff --git a/classes/class_inputeventaction.rst b/classes/class_inputeventaction.rst index 498f328ac..c179b483d 100644 --- a/classes/class_inputeventaction.rst +++ b/classes/class_inputeventaction.rst @@ -12,14 +12,14 @@ InputEventAction **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for actions. +An input event type for actions. .. rst-class:: classref-introduction-group Description ----------- -Contains a generic action which can be targeted from several types of inputs. Actions can be created from the **Input Map** tab in the **Project > Project Settings** menu. See :ref:`Node._input`. +Contains a generic action which can be targeted from several types of inputs. Actions and their events can be set in the **Input Map** tab in **Project > Project Settings**, or with the :ref:`InputMap` class. \ **Note:** Unlike the other :ref:`InputEvent` subclasses which map to unique physical events, this virtual one is not emitted by the engine. This class is useful to emit actions manually with :ref:`Input.parse_input_event`, which are then received in :ref:`Node._input`. To check if a physical event matches an action from the Input Map, use :ref:`InputEvent.is_action` and :ref:`InputEvent.is_action_pressed`. @@ -28,7 +28,7 @@ Contains a generic action which can be targeted from several types of inputs. Ac Tutorials --------- -- `InputEvent: Actions <../tutorials/inputs/inputevent.html#actions>`__ +- `Using InputEvent: Actions <../tutorials/inputs/inputevent.html#actions>`__ - `2D Dodge The Creeps Demo `__ diff --git a/classes/class_inputeventfromwindow.rst b/classes/class_inputeventfromwindow.rst index e6a0be605..7008924eb 100644 --- a/classes/class_inputeventfromwindow.rst +++ b/classes/class_inputeventfromwindow.rst @@ -14,7 +14,7 @@ InputEventFromWindow **Inherited By:** :ref:`InputEventScreenDrag`, :ref:`InputEventScreenTouch`, :ref:`InputEventWithModifiers` -Base class for :ref:`Viewport`-based input events. +Abstract base class for :ref:`Viewport`-based input events. .. rst-class:: classref-introduction-group diff --git a/classes/class_inputeventgesture.rst b/classes/class_inputeventgesture.rst index a3f06a346..bb8f641aa 100644 --- a/classes/class_inputeventgesture.rst +++ b/classes/class_inputeventgesture.rst @@ -14,14 +14,21 @@ InputEventGesture **Inherited By:** :ref:`InputEventMagnifyGesture`, :ref:`InputEventPanGesture` -Base class for touch control gestures. +Abstract base class for touch gestures. .. rst-class:: classref-introduction-group Description ----------- -InputEventGesture is sent when a user performs a supported gesture on a touch screen. Gestures can't be emulated using mouse, because they typically require multi-touch. +InputEventGestures are sent when a user performs a supported gesture on a touch screen. Gestures can't be emulated using mouse, because they typically require multi-touch. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventjoypadbutton.rst b/classes/class_inputeventjoypadbutton.rst index 4a2381e50..33419bf88 100644 --- a/classes/class_inputeventjoypadbutton.rst +++ b/classes/class_inputeventjoypadbutton.rst @@ -12,7 +12,7 @@ InputEventJoypadButton **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event for gamepad buttons. +Represents a gamepad button being pressed or released. .. rst-class:: classref-introduction-group @@ -26,7 +26,7 @@ Input event type for gamepad buttons. For gamepad analog sticks and joysticks, s Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventjoypadmotion.rst b/classes/class_inputeventjoypadmotion.rst index 5c48d3557..2a7661e10 100644 --- a/classes/class_inputeventjoypadmotion.rst +++ b/classes/class_inputeventjoypadmotion.rst @@ -12,21 +12,21 @@ InputEventJoypadMotion **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for gamepad joysticks and other motions. For buttons, see ``InputEventJoypadButton``. +Represents axis motions (such as joystick or analog triggers) from a gamepad. .. rst-class:: classref-introduction-group Description ----------- -Stores information about joystick motions. One **InputEventJoypadMotion** represents one axis at a time. +Stores information about joystick motions. One **InputEventJoypadMotion** represents one axis at a time. For gamepad buttons, see :ref:`InputEventJoypadButton`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventkey.rst b/classes/class_inputeventkey.rst index 24ff2ddcc..a11a557fb 100644 --- a/classes/class_inputeventkey.rst +++ b/classes/class_inputeventkey.rst @@ -12,25 +12,25 @@ InputEventKey **Inherits:** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for keyboard events. +Represents a key on a keyboard being pressed or released. .. rst-class:: classref-introduction-group Description ----------- -Stores key presses on the keyboard. Supports key presses, key releases and :ref:`echo` events. +An input event for keys on a keyboard. Supports key presses, key releases and :ref:`echo` events. It can also be received in :ref:`Node._unhandled_key_input`. \ **Note:** Events received from the keyboard usually have all properties set. Event mappings should have only one of the :ref:`keycode`, :ref:`physical_keycode` or :ref:`unicode` set. -When events are compared, properties are checked in the following priority - :ref:`keycode`, :ref:`physical_keycode` and :ref:`unicode`, events with the first matching value will be considered equal. +When events are compared, properties are checked in the following priority - :ref:`keycode`, :ref:`physical_keycode` and :ref:`unicode`. Events with the first matching value will be considered equal. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventmagnifygesture.rst b/classes/class_inputeventmagnifygesture.rst index 3f79c74f0..75339ae6c 100644 --- a/classes/class_inputeventmagnifygesture.rst +++ b/classes/class_inputeventmagnifygesture.rst @@ -12,14 +12,21 @@ InputEventMagnifyGesture **Inherits:** :ref:`InputEventGesture` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`InputEvent` that represents a magnifying touch gesture. +Represents a magnifying touch gesture. .. rst-class:: classref-introduction-group Description ----------- -Magnify gesture is performed when the user pinches the touch screen. It's typically used for zooming. +Stores the factor of a magnifying touch gesture. This is usually performed when the user pinches the touch screen and used for zooming in/out. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group @@ -53,7 +60,7 @@ Property Descriptions - void **set_factor** **(** :ref:`float` value **)** - :ref:`float` **get_factor** **(** **)** -The amount (or delta) of the event. This value is higher the faster the gesture is performed. +The amount (or delta) of the event. This value is closer to ``1.0`` the slower the gesture is performed. .. |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_inputeventmidi.rst b/classes/class_inputeventmidi.rst index 67e4bf366..3056ce461 100644 --- a/classes/class_inputeventmidi.rst +++ b/classes/class_inputeventmidi.rst @@ -12,14 +12,14 @@ InputEventMIDI **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event for MIDI inputs. +Represents an input event from a MIDI device, such as a piano. .. rst-class:: classref-introduction-group Description ----------- -InputEventMIDI allows receiving input events from MIDI devices such as a piano. MIDI stands for Musical Instrument Digital Interface. +InputEventMIDI allows receiving input events from MIDI (Musical Instrument Digital Interface) devices such as a piano. MIDI signals can be sent over a 5-pin MIDI connector or over USB, if your device supports both be sure to check the settings in the device to see which output it's using. diff --git a/classes/class_inputeventmouse.rst b/classes/class_inputeventmouse.rst index c8ab4e040..4ba08011a 100644 --- a/classes/class_inputeventmouse.rst +++ b/classes/class_inputeventmouse.rst @@ -21,14 +21,14 @@ Base input event type for mouse events. Description ----------- -Stores general mouse events information. +Stores general information about mouse events. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventmousebutton.rst b/classes/class_inputeventmousebutton.rst index 0cd979ca8..fb0d834a7 100644 --- a/classes/class_inputeventmousebutton.rst +++ b/classes/class_inputeventmousebutton.rst @@ -12,20 +12,22 @@ InputEventMouseButton **Inherits:** :ref:`InputEventMouse` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for mouse button events. +Represents a mouse button being pressed or released. .. rst-class:: classref-introduction-group Description ----------- -Contains mouse click information. See :ref:`Node._input`. +Stores information about mouse click events. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` + - :doc:`Mouse and input coordinates <../tutorials/inputs/mouse_and_input_coordinates>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventmousemotion.rst b/classes/class_inputeventmousemotion.rst index 46d804167..ac5e2218b 100644 --- a/classes/class_inputeventmousemotion.rst +++ b/classes/class_inputeventmousemotion.rst @@ -12,14 +12,14 @@ InputEventMouseMotion **Inherits:** :ref:`InputEventMouse` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for mouse motion events. +Represents a mouse or a pen movement. .. rst-class:: classref-introduction-group Description ----------- -Contains mouse and pen motion information. Supports relative, absolute positions and velocity. See :ref:`Node._input`. +Stores information about a mouse or a pen motion. This includes relative position, absolute position, and velocity. See :ref:`Node._input`. \ **Note:** By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, set :ref:`Input.use_accumulated_input` to ``false`` to make events emitted as often as possible. If you use InputEventMouseMotion to draw lines, consider implementing `Bresenham's line algorithm `__ as well to avoid visible gaps in lines if the user is moving the mouse quickly. @@ -28,6 +28,8 @@ Contains mouse and pen motion information. Supports relative, absolute positions Tutorials --------- +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` + - :doc:`Mouse and input coordinates <../tutorials/inputs/mouse_and_input_coordinates>` - `3D Voxel Demo `__ diff --git a/classes/class_inputeventpangesture.rst b/classes/class_inputeventpangesture.rst index af25858ea..9c90171ee 100644 --- a/classes/class_inputeventpangesture.rst +++ b/classes/class_inputeventpangesture.rst @@ -12,14 +12,21 @@ InputEventPanGesture **Inherits:** :ref:`InputEventGesture` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`InputEvent` that represents a panning touch gesture. +Represents a panning touch gesture. .. rst-class:: classref-introduction-group Description ----------- -Pan gesture is performed when the user swipes the touch screen with two fingers. It's typically used for panning/scrolling. +Stores information about pan gestures. A pan gesture is performed when the user swipes the touch screen with two fingers. It's typically used for panning/scrolling. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventscreendrag.rst b/classes/class_inputeventscreendrag.rst index 2b0b0e277..ce312dedd 100644 --- a/classes/class_inputeventscreendrag.rst +++ b/classes/class_inputeventscreendrag.rst @@ -12,21 +12,21 @@ InputEventScreenDrag **Inherits:** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for screen drag events. Only available on mobile devices. +Represents a screen drag event. .. rst-class:: classref-introduction-group Description ----------- -Contains screen drag information. See :ref:`Node._input`. +Stores information about screen drag events. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventscreentouch.rst b/classes/class_inputeventscreentouch.rst index 1c4b76b1d..cbd986f55 100644 --- a/classes/class_inputeventscreentouch.rst +++ b/classes/class_inputeventscreentouch.rst @@ -12,23 +12,21 @@ InputEventScreenTouch **Inherits:** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for screen touch events. - -(only available on mobile devices) +Represents a screen touch event. .. rst-class:: classref-introduction-group Description ----------- -Stores multi-touch press/release information. Supports touch press, touch release and :ref:`index` for multi-touch count and order. +Stores information about multi-touch press/release input events. Supports touch press, touch release and :ref:`index` for multi-touch count and order. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventshortcut.rst b/classes/class_inputeventshortcut.rst index a4da5ead5..c56defc18 100644 --- a/classes/class_inputeventshortcut.rst +++ b/classes/class_inputeventshortcut.rst @@ -12,14 +12,14 @@ InputEventShortcut **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`InputEvent` that signifies a triggered keyboard :ref:`Shortcut`. +Represents a triggered keyboard :ref:`Shortcut`. .. rst-class:: classref-introduction-group Description ----------- -InputEventShortcut is a special event that can be received in :ref:`Node._unhandled_key_input`. It's typically sent by the editor's Command Palette to trigger actions, but can also be sent manually using :ref:`Viewport.push_unhandled_input`. +InputEventShortcut is a special event that can be received in :ref:`Node._unhandled_key_input`. It is typically sent by the editor's Command Palette to trigger actions, but can also be sent manually using :ref:`Viewport.push_unhandled_input`. .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventwithmodifiers.rst b/classes/class_inputeventwithmodifiers.rst index 57c94bbc2..6d92a89cd 100644 --- a/classes/class_inputeventwithmodifiers.rst +++ b/classes/class_inputeventwithmodifiers.rst @@ -14,21 +14,21 @@ InputEventWithModifiers **Inherited By:** :ref:`InputEventGesture`, :ref:`InputEventKey`, :ref:`InputEventMouse` -Base class for keys events with modifiers. +Abstract base class for input events affected by modifier keys like :kbd:`Shift` and :kbd:`Alt`. .. rst-class:: classref-introduction-group Description ----------- -Contains keys events information with modifiers support like :kbd:`Shift` or :kbd:`Alt`. See :ref:`Node._input`. +Stores information about mouse, keyboard, and touch gesture input events. This includes information about which modifier keys are pressed, such as :kbd:`Shift` or :kbd:`Alt`. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputmap.rst b/classes/class_inputmap.rst index 84beda741..e0f273b05 100644 --- a/classes/class_inputmap.rst +++ b/classes/class_inputmap.rst @@ -12,7 +12,7 @@ InputMap **Inherits:** :ref:`Object` -Singleton that manages :ref:`InputEventAction`. +A singleton that manages all :ref:`InputEventAction`\ s. .. rst-class:: classref-introduction-group @@ -26,7 +26,7 @@ Manages all :ref:`InputEventAction` which can be created Tutorials --------- -- `InputEvent: InputMap <../tutorials/inputs/inputevent.html#inputmap>`__ +- `Using InputEvent: InputMap <../tutorials/inputs/inputevent.html#inputmap>`__ .. rst-class:: classref-reftable-group diff --git a/classes/class_int.rst b/classes/class_int.rst index b772da13f..9855a553c 100644 --- a/classes/class_int.rst +++ b/classes/class_int.rst @@ -10,7 +10,7 @@ int === -Built-in integer Variant type. +A built-in type for integers. .. rst-class:: classref-introduction-group diff --git a/classes/class_itemlist.rst b/classes/class_itemlist.rst index fc96bdaf1..b56934398 100644 --- a/classes/class_itemlist.rst +++ b/classes/class_itemlist.rst @@ -12,20 +12,20 @@ ItemList **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control that provides a list of selectable items (and/or icons) in a single column, or optionally in multiple columns. +A vertical list of selectable items with one or multiple columns. .. rst-class:: classref-introduction-group Description ----------- -This control provides a selectable list of items that may be in a single (or multiple columns) with option of text, icons, or both text and icon. Tooltips are supported and may be different for every item in the list. +This control provides a vertical list of selectable items that may be in a single or in multiple columns, with each item having options for text and an icon. Tooltips are supported and may be different for every item in the list. Selectable items in the list may be selected or deselected and multiple selection may be enabled. Selection with right mouse button may also be enabled to allow use of popup context menus. Items may also be "activated" by double-clicking them or by pressing :kbd:`Enter`. -Item text only supports single-line strings, newline characters (e.g. ``\n``) in the string won't produce a newline. Text wrapping is enabled in :ref:`ICON_MODE_TOP` mode, but column's width is adjusted to fully fit its content by default. You need to set :ref:`fixed_column_width` greater than zero to wrap the text. +Item text only supports single-line strings. Newline characters (e.g. ``\n``) in the string won't produce a newline. Text wrapping is enabled in :ref:`ICON_MODE_TOP` mode, but the column's width is adjusted to fully fit its content by default. You need to set :ref:`fixed_column_width` greater than zero to wrap the text. -All ``set_*`` methods allow negative item index, which makes the item accessed from the last one. +All ``set_*`` methods allow negative item indices, i.e. ``-1`` to access the last item, ``-2`` to select the second-to-last item, and so on. \ **Incremental search:** Like :ref:`PopupMenu` and :ref:`Tree`, **ItemList** supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing :ref:`ProjectSettings.gui/timers/incremental_search_max_interval_msec`. diff --git a/classes/class_javascriptobject.rst b/classes/class_javascriptobject.rst index 06edf00f5..8dc158b0c 100644 --- a/classes/class_javascriptobject.rst +++ b/classes/class_javascriptobject.rst @@ -27,7 +27,7 @@ JavaScriptObject is used to interact with JavaScript objects retrieved or create extends Node - var _my_js_callback = JavaScriptBridge.create_callback(self, "myCallback") # This reference must be kept + var _my_js_callback = JavaScriptBridge.create_callback(myCallback) # This reference must be kept var console = JavaScriptBridge.get_interface("console") func _init(): diff --git a/classes/class_label.rst b/classes/class_label.rst index 23a38796f..4c5b5d7c7 100644 --- a/classes/class_label.rst +++ b/classes/class_label.rst @@ -12,16 +12,14 @@ Label **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Displays plain text in a line or wrapped inside a rectangle. For formatted text, use :ref:`RichTextLabel`. +A control for displaying plain text. .. rst-class:: classref-introduction-group Description ----------- -Label displays plain text on the screen. It gives you control over the horizontal and vertical alignment and can wrap the text inside the node's bounding rectangle. It doesn't support bold, italics, or other formatting. For that, use :ref:`RichTextLabel` instead. - -\ **Note:** Contrarily to most other :ref:`Control`\ s, Label's :ref:`Control.mouse_filter` defaults to :ref:`Control.MOUSE_FILTER_IGNORE` (i.e. it doesn't react to mouse input events). This implies that a label won't display any configured :ref:`Control.tooltip_text`, unless you change its mouse filter. +A control for displaying plain text. It gives you control over the horizontal and vertical alignment and can wrap the text inside the node's bounding rectangle. It doesn't support bold, italics, or other rich text formatting. For that, use :ref:`RichTextLabel` instead. .. rst-class:: classref-introduction-group diff --git a/classes/class_label3d.rst b/classes/class_label3d.rst index 30b563513..cf10441fb 100644 --- a/classes/class_label3d.rst +++ b/classes/class_label3d.rst @@ -12,14 +12,14 @@ Label3D **Inherits:** :ref:`GeometryInstance3D` **<** :ref:`VisualInstance3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Displays plain text in a 3D world. +A node for displaying plain text in 3D space. .. rst-class:: classref-introduction-group Description ----------- -Label3D displays plain text in a 3D world. It gives you control over the horizontal and vertical alignment. +A node for displaying plain text in 3D space. By adjusting various properties of this node, you can configure things such as the text's appearance and whether it always faces the camera. .. rst-class:: classref-reftable-group diff --git a/classes/class_labelsettings.rst b/classes/class_labelsettings.rst index c10c6fcce..2e8d052c0 100644 --- a/classes/class_labelsettings.rst +++ b/classes/class_labelsettings.rst @@ -12,14 +12,14 @@ LabelSettings **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Collection of common settings to customize label text. +Provides common settings to customize the text in a :ref:`Label`. .. rst-class:: classref-introduction-group Description ----------- -**LabelSettings** is a resource that can be assigned to a :ref:`Label` node to customize it. It will take priority over the properties defined in theme. The resource can be shared between multiple labels and swapped on the fly, so it's convenient and flexible way to setup text style. +**LabelSettings** is a resource that provides common settings to customize the text in a :ref:`Label`. It will take priority over the properties defined in :ref:`Control.theme`. The resource can be shared between multiple labels and changed on the fly, so it's convenient and flexible way to setup text style. .. rst-class:: classref-reftable-group diff --git a/classes/class_lineedit.rst b/classes/class_lineedit.rst index 543ea7dd0..715d40bf8 100644 --- a/classes/class_lineedit.rst +++ b/classes/class_lineedit.rst @@ -12,16 +12,14 @@ LineEdit **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control that provides single-line string editing. +An input field for single-line text. .. rst-class:: classref-introduction-group Description ----------- -LineEdit provides a single-line string editor, used for text fields. - -It features many built-in shortcuts which will always be available (:kbd:`Ctrl` here maps to :kbd:`Cmd` on macOS): +**LineEdit** provides an input field for editing a single line of text. It features many built-in shortcuts that are always available (:kbd:`Ctrl` here maps to :kbd:`Cmd` on macOS): - :kbd:`Ctrl + C`: Copy @@ -45,21 +43,21 @@ It features many built-in shortcuts which will always be available (:kbd:`Ctrl` On macOS, some extra keyboard shortcuts are available: -- :kbd:`Ctrl + F`: Same as :kbd:`Right Arrow`, move the caret one character right +- :kbd:`Cmd + F`: Same as :kbd:`Right Arrow`, move the caret one character right -- :kbd:`Ctrl + B`: Same as :kbd:`Left Arrow`, move the caret one character left +- :kbd:`Cmd + B`: Same as :kbd:`Left Arrow`, move the caret one character left -- :kbd:`Ctrl + P`: Same as :kbd:`Up Arrow`, move the caret to the previous line +- :kbd:`Cmd + P`: Same as :kbd:`Up Arrow`, move the caret to the previous line -- :kbd:`Ctrl + N`: Same as :kbd:`Down Arrow`, move the caret to the next line +- :kbd:`Cmd + N`: Same as :kbd:`Down Arrow`, move the caret to the next line -- :kbd:`Ctrl + D`: Same as :kbd:`Delete`, delete the character on the right side of caret +- :kbd:`Cmd + D`: Same as :kbd:`Delete`, delete the character on the right side of caret -- :kbd:`Ctrl + H`: Same as :kbd:`Backspace`, delete the character on the left side of the caret +- :kbd:`Cmd + H`: Same as :kbd:`Backspace`, delete the character on the left side of the caret -- :kbd:`Ctrl + A`: Same as :kbd:`Home`, move the caret to the beginning of the line +- :kbd:`Cmd + A`: Same as :kbd:`Home`, move the caret to the beginning of the line -- :kbd:`Ctrl + E`: Same as :kbd:`End`, move the caret to the end of the line +- :kbd:`Cmd + E`: Same as :kbd:`End`, move the caret to the end of the line - :kbd:`Cmd + Left Arrow`: Same as :kbd:`Home`, move the caret to the beginning of the line @@ -727,7 +725,7 @@ Allow moving caret, selecting and removing the individual composite character co - void **set_clear_button_enabled** **(** :ref:`bool` value **)** - :ref:`bool` **is_clear_button_enabled** **(** **)** -If ``true``, the **LineEdit** will show a clear button if ``text`` is not empty, which can be used to clear the text quickly. +If ``true``, the **LineEdit** will show a clear button if :ref:`text` is not empty, which can be used to clear the text quickly. .. rst-class:: classref-item-separator @@ -1572,7 +1570,7 @@ Texture for the clear button. See :ref:`clear_button_enabled` **focus** -Background used when **LineEdit** has GUI focus. The ``focus`` :ref:`StyleBox` is displayed *over* the base :ref:`StyleBox`, so a partially transparent :ref:`StyleBox` should be used to ensure the base :ref:`StyleBox` remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. +Background used when **LineEdit** has GUI focus. The :ref:`focus` :ref:`StyleBox` is displayed *over* the base :ref:`StyleBox`, so a partially transparent :ref:`StyleBox` should be used to ensure the base :ref:`StyleBox` remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. .. rst-class:: classref-item-separator diff --git a/classes/class_linkbutton.rst b/classes/class_linkbutton.rst index 5cfd36b8f..e1a29ad30 100644 --- a/classes/class_linkbutton.rst +++ b/classes/class_linkbutton.rst @@ -12,14 +12,14 @@ LinkButton **Inherits:** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Simple button used to represent a link to some resource. +A button that represents a link. .. rst-class:: classref-introduction-group Description ----------- -This kind of button is primarily used when the interaction with the button causes a context change (like linking to a web page). +A button that represents a link. This type of button is primarily used for interactions that cause a context change (like linking to a web page). See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_margincontainer.rst b/classes/class_margincontainer.rst index 3539524aa..3d602da86 100644 --- a/classes/class_margincontainer.rst +++ b/classes/class_margincontainer.rst @@ -12,16 +12,16 @@ MarginContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Simple margin container. +A container that keeps a margin around its child controls. .. rst-class:: classref-introduction-group Description ----------- -Adds a top, left, bottom, and right margin to all :ref:`Control` nodes that are direct children of the container. To control the **MarginContainer**'s margin, use the ``margin_*`` theme properties listed below. +**MarginContainer** adds an adjustable margin on each side of its child controls. The margins are added around all children, not around each individual one. To control the **MarginContainer**'s margins, use the ``margin_*`` theme properties listed below. -\ **Note:** Be careful, :ref:`Control` margin values are different from the constant margin values. If you want to change the custom margin values of the **MarginContainer** by code, you should use the following examples: +\ **Note:** The margin sizes are theme overrides, not normal properties. This is an example of how to change them in code: .. tabs:: @@ -51,7 +51,7 @@ Adds a top, left, bottom, and right margin to all :ref:`Control` Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_menubar.rst b/classes/class_menubar.rst index 33c418dfb..993e95066 100644 --- a/classes/class_menubar.rst +++ b/classes/class_menubar.rst @@ -12,14 +12,14 @@ MenuBar **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -A horizontal menu bar, which displays :ref:`PopupMenu`\ s or system global menu. +A horizontal menu bar that creates a :ref:`MenuButton` for each :ref:`PopupMenu` child. .. rst-class:: classref-introduction-group Description ----------- -New items can be created by adding :ref:`PopupMenu` nodes to this node. +A horizontal menu bar that creates a :ref:`MenuButton` for each :ref:`PopupMenu` child. New items are created by adding :ref:`PopupMenu`\ s to this node. .. rst-class:: classref-reftable-group diff --git a/classes/class_menubutton.rst b/classes/class_menubutton.rst index 64d138c23..26f6cdb4d 100644 --- a/classes/class_menubutton.rst +++ b/classes/class_menubutton.rst @@ -12,16 +12,14 @@ MenuButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Special button that brings up a :ref:`PopupMenu` when clicked. +A button that brings up a :ref:`PopupMenu` when clicked. .. rst-class:: classref-introduction-group Description ----------- -Special button that brings up a :ref:`PopupMenu` when clicked. - -New items can be created inside this :ref:`PopupMenu` using ``get_popup().add_item("My Item Name")``. You can also create them directly from the editor. To do so, select the **MenuButton** node, then in the toolbar at the top of the 2D editor, click **Items** then click **Add** in the popup. You will be able to give each item new properties. +A button that brings up a :ref:`PopupMenu` when clicked. To create new items inside this :ref:`PopupMenu`, use ``get_popup().add_item("My Item Name")``. You can also create them directly from Godot editor's inspector. See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_missingnode.rst b/classes/class_missingnode.rst index 4f099b930..198f9985f 100644 --- a/classes/class_missingnode.rst +++ b/classes/class_missingnode.rst @@ -12,7 +12,7 @@ MissingNode **Inherits:** :ref:`Node` **<** :ref:`Object` -This is an internal editor class intended for keeping data of nodes of unknown type. +An internal editor class intended for keeping the data of unrecognized nodes. .. rst-class:: classref-introduction-group @@ -55,9 +55,7 @@ Property Descriptions - void **set_original_class** **(** :ref:`String` value **)** - :ref:`String` **get_original_class** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Returns the name of the type this node was originally. .. rst-class:: classref-item-separator diff --git a/classes/class_missingresource.rst b/classes/class_missingresource.rst index 6cdb58a0a..0359d9970 100644 --- a/classes/class_missingresource.rst +++ b/classes/class_missingresource.rst @@ -12,7 +12,7 @@ MissingResource **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -This is an internal editor class intended for keeping data of resources of unknown type. +An internal editor class intended for keeping the data of unrecognized resources. .. rst-class:: classref-introduction-group @@ -55,9 +55,7 @@ Property Descriptions - void **set_original_class** **(** :ref:`String` value **)** - :ref:`String` **get_original_class** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Returns the name of the class this resource was originally. .. rst-class:: classref-item-separator diff --git a/classes/class_multiplayersynchronizer.rst b/classes/class_multiplayersynchronizer.rst index 20a058415..9bf07da62 100644 --- a/classes/class_multiplayersynchronizer.rst +++ b/classes/class_multiplayersynchronizer.rst @@ -292,7 +292,7 @@ Sets the visibility of ``peer`` to ``visible``. If ``peer`` is ``0``, the value void **update_visibility** **(** :ref:`int` for_peer=0 **)** -Updates the visibility of ``peer`` according to visibility filters. If ``peer`` is ``0`` (the default), all peers' visibilties are updated. +Updates the visibility of ``for_peer`` according to visibility filters. If ``for_peer`` is ``0`` (the default), all peers' visibilties are updated. .. |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_mutex.rst b/classes/class_mutex.rst index 433ed625b..50752db00 100644 --- a/classes/class_mutex.rst +++ b/classes/class_mutex.rst @@ -12,7 +12,7 @@ Mutex **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A synchronization mutex (mutual exclusion). +A binary :ref:`Semaphore` for synchronization of multiple :ref:`Thread`\ s. .. rst-class:: classref-introduction-group @@ -28,6 +28,8 @@ Tutorials - :doc:`Using multiple threads <../tutorials/performance/using_multiple_threads>` +- :doc:`Thread-safe APIs <../tutorials/performance/thread_safe_apis>` + .. rst-class:: classref-reftable-group Methods @@ -75,7 +77,7 @@ Locks this **Mutex**, blocks until it is unlocked by the current owner. Tries locking this **Mutex**, but does not block. Returns ``true`` on success, ``false`` otherwise. -\ **Note:** This function returns :ref:`@GlobalScope.OK` if the thread already has ownership of the mutex. +\ **Note:** This function returns ``true`` if the thread already has ownership of the mutex. .. rst-class:: classref-item-separator diff --git a/classes/class_navigationlink2d.rst b/classes/class_navigationlink2d.rst index 598b54fa5..0d0148f77 100644 --- a/classes/class_navigationlink2d.rst +++ b/classes/class_navigationlink2d.rst @@ -149,7 +149,7 @@ The distance the link will search is controlled by :ref:`NavigationServer2D.map_ - void **set_enter_cost** **(** :ref:`float` value **)** - :ref:`float` **get_enter_cost** **(** **)** -When pathfinding enters this link from another regions navigation mesh the ``enter_cost`` value is added to the path distance for determining the shortest path. +When pathfinding enters this link from another regions navigation mesh the :ref:`enter_cost` value is added to the path distance for determining the shortest path. .. rst-class:: classref-item-separator @@ -204,7 +204,7 @@ The distance the link will search is controlled by :ref:`NavigationServer2D.map_ - void **set_travel_cost** **(** :ref:`float` value **)** - :ref:`float` **get_travel_cost** **(** **)** -When pathfinding moves along the link the traveled distance is multiplied with ``travel_cost`` for determining the shortest path. +When pathfinding moves along the link the traveled distance is multiplied with :ref:`travel_cost` for determining the shortest path. .. rst-class:: classref-section-separator diff --git a/classes/class_navigationlink3d.rst b/classes/class_navigationlink3d.rst index 1164a638d..0de2e4ff5 100644 --- a/classes/class_navigationlink3d.rst +++ b/classes/class_navigationlink3d.rst @@ -149,7 +149,7 @@ The distance the link will search is controlled by :ref:`NavigationServer3D.map_ - void **set_enter_cost** **(** :ref:`float` value **)** - :ref:`float` **get_enter_cost** **(** **)** -When pathfinding enters this link from another regions navigation mesh the ``enter_cost`` value is added to the path distance for determining the shortest path. +When pathfinding enters this link from another regions navigation mesh the :ref:`enter_cost` value is added to the path distance for determining the shortest path. .. rst-class:: classref-item-separator @@ -204,7 +204,7 @@ The distance the link will search is controlled by :ref:`NavigationServer3D.map_ - void **set_travel_cost** **(** :ref:`float` value **)** - :ref:`float` **get_travel_cost** **(** **)** -When pathfinding moves along the link the traveled distance is multiplied with ``travel_cost`` for determining the shortest path. +When pathfinding moves along the link the traveled distance is multiplied with :ref:`travel_cost` for determining the shortest path. .. rst-class:: classref-section-separator diff --git a/classes/class_ninepatchrect.rst b/classes/class_ninepatchrect.rst index 9d1bc7402..c442839dd 100644 --- a/classes/class_ninepatchrect.rst +++ b/classes/class_ninepatchrect.rst @@ -12,14 +12,14 @@ NinePatchRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Scalable texture-based frame that tiles the texture's centers and sides, but keeps the corners' original size. Perfect for panels and dialog boxes. +A control that displays a texture by keeping its corners intact, but tiling its edges and center. .. rst-class:: classref-introduction-group Description ----------- -Also known as 9-slice panels, NinePatchRect produces clean panels of any size, based on a small texture. To do so, it splits the texture in a 3×3 grid. When you scale the node, it tiles the texture's sides horizontally or vertically, the center on both axes but it doesn't scale or tile the corners. +Also known as 9-slice panels, **NinePatchRect** produces clean panels of any size based on a small texture. To do so, it splits the texture in a 3×3 grid. When you scale the node, it tiles the texture's edges horizontally or vertically, tiles the center on both axes, and leaves the corners unchanged. .. rst-class:: classref-reftable-group diff --git a/classes/class_node.rst b/classes/class_node.rst index cfc9b2c86..19039fc8c 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -14,7 +14,7 @@ Node **Inherited By:** :ref:`AnimationPlayer`, :ref:`AnimationTree`, :ref:`AudioStreamPlayer`, :ref:`CanvasItem`, :ref:`CanvasLayer`, :ref:`EditorFileSystem`, :ref:`EditorInterface`, :ref:`EditorPlugin`, :ref:`EditorResourcePreview`, :ref:`HTTPRequest`, :ref:`InstancePlaceholder`, :ref:`MissingNode`, :ref:`MultiplayerSpawner`, :ref:`MultiplayerSynchronizer`, :ref:`NavigationAgent2D`, :ref:`NavigationAgent3D`, :ref:`NavigationObstacle2D`, :ref:`NavigationObstacle3D`, :ref:`Node3D`, :ref:`ResourcePreloader`, :ref:`ShaderGlobalsOverride`, :ref:`SkeletonIK3D`, :ref:`Timer`, :ref:`Viewport`, :ref:`WorldEnvironment` -Base class for all *scene* objects. +Base class for all scene objects. .. rst-class:: classref-introduction-group diff --git a/classes/class_nodepath.rst b/classes/class_nodepath.rst index d3285efd6..404566fb7 100644 --- a/classes/class_nodepath.rst +++ b/classes/class_nodepath.rst @@ -10,7 +10,7 @@ NodePath ======== -Pre-parsed scene tree path. +A pre-parsed scene tree path. .. rst-class:: classref-introduction-group @@ -42,6 +42,8 @@ See also :ref:`StringName`, which is a similar concept for gen \ **Note:** In the editor, **NodePath** properties are automatically updated when moving, renaming or deleting a node in the scene tree, but they are never updated at runtime. +\ **Note:** In a boolean context, a **NodePath** will evaluate to ``false`` if it is empty (``NodePath("")``). Otherwise, a **NodePath** will always evaluate to ``true``. + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_noisetexture2d.rst b/classes/class_noisetexture2d.rst index c9c6c2447..88a83e7f5 100644 --- a/classes/class_noisetexture2d.rst +++ b/classes/class_noisetexture2d.rst @@ -19,9 +19,7 @@ A texture filled with noise generated by a :ref:`Noise` object. Description ----------- -Uses :ref:`FastNoiseLite` or other libraries to fill the texture data of your desired size. - -NoiseTexture2D can also generate normalmap textures. +Uses :ref:`FastNoiseLite` or other libraries to fill the texture data of your desired size. **NoiseTexture2D** can also generate normal map textures. The class uses :ref:`Thread`\ s to generate the texture data internally, so :ref:`Texture2D.get_image` may return ``null`` if the generation process has not completed yet. In that case, you need to wait for the texture to be generated before accessing the image and the generated byte data: @@ -140,11 +138,9 @@ A :ref:`Gradient` which is used to map the luminance of each pix - void **set_generate_mipmaps** **(** :ref:`bool` value **)** - :ref:`bool` **is_generating_mipmaps** **(** **)** -Determines whether mipmaps are generated for this texture. +Determines whether mipmaps are generated for this texture. Enabling this results in less texture aliasing in the distance, at the cost of increasing memory usage by roughly 33% and making the noise texture generation take longer. -Enabling this results in less texture aliasing, but the noise texture generation may take longer. - -Requires (anisotropic) mipmap filtering to be enabled for a material to have an effect. +\ **Note:** :ref:`generate_mipmaps` requires mipmap filtering to be enabled on the material using the **NoiseTexture2D** to have an effect. .. rst-class:: classref-item-separator @@ -161,7 +157,7 @@ Requires (anisotropic) mipmap filtering to be enabled for a material to have an - void **set_height** **(** :ref:`int` value **)** - :ref:`int` **get_height** **(** **)** -Height of the generated texture. +Height of the generated texture (in pixels). .. rst-class:: classref-item-separator @@ -252,6 +248,8 @@ If ``true``, a seamless texture is requested from the :ref:`Noise` \ **Note:** Seamless noise textures may take longer to generate and/or can have a lower contrast compared to non-seamless noise depending on the used :ref:`Noise` resource. This is because some implementations use higher dimensions for generating seamless noise. +\ **Note:** The default :ref:`FastNoiseLite` implementation uses the fallback path for seamless generation. If using a :ref:`width` or :ref:`height` lower than the default, you may need to increase :ref:`seamless_blend_skirt` to make seamless blending more effective. + .. rst-class:: classref-item-separator ---- @@ -269,6 +267,8 @@ If ``true``, a seamless texture is requested from the :ref:`Noise` Used for the default/fallback implementation of the seamless texture generation. It determines the distance over which the seams are blended. High values may result in less details and contrast. See :ref:`Noise` for further details. +\ **Note:** If using a :ref:`width` or :ref:`height` lower than the default, you may need to increase :ref:`seamless_blend_skirt` to make seamless blending more effective. + .. rst-class:: classref-item-separator ---- @@ -284,7 +284,7 @@ Used for the default/fallback implementation of the seamless texture generation. - void **set_width** **(** :ref:`int` value **)** - :ref:`int` **get_width** **(** **)** -Width of the generated texture. +Width of the generated texture (in pixels). .. |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_object.rst b/classes/class_object.rst index bf18aa559..ba9a2885f 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -472,7 +472,7 @@ Called when the object receives a notification, which can be identified in ``wha .. code-tab:: csharp - public override void _Notification(long what) + public override void _Notification(int what) { if (what == NotificationPredelete) { @@ -1068,7 +1068,9 @@ Returns the object's unique instance ID. This ID can be saved in :ref:`EncodedOb Returns the object's metadata value for the given entry ``name``. If the entry does not exist, returns ``default``. If ``default`` is ``null``, an error is also generated. -\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector dock and should not be edited. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + +\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator @@ -1188,6 +1190,8 @@ Returns the list of existing signals as an :ref:`Array` of dictiona Returns ``true`` if a metadata entry is found with the given ``name``. See also :ref:`get_meta`, :ref:`set_meta` and :ref:`remove_meta`. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + \ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator @@ -1394,7 +1398,9 @@ void **remove_meta** **(** :ref:`StringName` name **)** Removes the given entry ``name`` from the object's metadata. See also :ref:`has_meta`, :ref:`get_meta` and :ref:`set_meta`. -\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + +\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator @@ -1539,7 +1545,9 @@ Adds or changes the entry ``name`` inside the object's metadata. The metadata `` If ``value`` is ``null``, the entry is removed. This is the equivalent of using :ref:`remove_meta`. See also :ref:`has_meta` and :ref:`get_meta`. -\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector dock and should not be edited. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + +\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator diff --git a/classes/class_optimizedtranslation.rst b/classes/class_optimizedtranslation.rst index 9cf8a0a5d..3a93b89b6 100644 --- a/classes/class_optimizedtranslation.rst +++ b/classes/class_optimizedtranslation.rst @@ -12,14 +12,14 @@ OptimizedTranslation **Inherits:** :ref:`Translation` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Optimized translation. +An optimized translation, used by default for CSV Translations. .. rst-class:: classref-introduction-group Description ----------- -Optimized translation. Uses real-time compressed translations, which results in very small dictionaries. +An optimized translation, used by default for CSV Translations. Uses real-time compressed translations, which results in very small dictionaries. .. rst-class:: classref-reftable-group diff --git a/classes/class_optionbutton.rst b/classes/class_optionbutton.rst index afb53e8f0..c4ffd18c8 100644 --- a/classes/class_optionbutton.rst +++ b/classes/class_optionbutton.rst @@ -12,19 +12,25 @@ OptionButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Button control that provides selectable options when pressed. +A button that brings up a dropdown with selectable options when pressed. .. rst-class:: classref-introduction-group Description ----------- -OptionButton is a type button that provides a selectable list of items when pressed. The item selected becomes the "current" item and is displayed as the button text. +**OptionButton** is a type of button that brings up a dropdown with selectable items when pressed. The item selected becomes the "current" item and is displayed as the button text. See also :ref:`BaseButton` which contains common properties and methods associated with this node. \ **Note:** Properties :ref:`Button.text` and :ref:`Button.icon` are automatically set based on the selected item. They shouldn't be changed manually. +\ **Note:** The ID values used for items are limited to 32 bits, not full 64 bits of :ref:`int`. This has a range of ``-2^32`` to ``2^32 - 1``, i.e. ``-2147483648`` to ``2147483647``. + +\ **Note:** The ID values used for items are 32-bit, unlike :ref:`int` which is always 64-bit. They go from ``-2147483648`` to ``2147483647``. + +\ **Note:** The :ref:`Button.text` and :ref:`Button.icon` properties are set automatically based on the selected item. They shouldn't be changed manually. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_os.rst b/classes/class_os.rst index 1d695dc2a..19668dbfe 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -12,14 +12,14 @@ OS **Inherits:** :ref:`Object` -Operating System functions. +Provides access to common operating system functionalities. .. rst-class:: classref-introduction-group Description ----------- -Operating System functions. **OS** wraps the most common functionality to communicate with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. +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. \ **Note:** In Godot 4, **OS** functions related to window management were moved to the :ref:`DisplayServer` singleton. diff --git a/classes/class_packeddatacontainerref.rst b/classes/class_packeddatacontainerref.rst index 0974386fd..3a6cce9f9 100644 --- a/classes/class_packeddatacontainerref.rst +++ b/classes/class_packeddatacontainerref.rst @@ -12,7 +12,7 @@ PackedDataContainerRef **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Reference-counted version of :ref:`PackedDataContainer`. +An internal class used by :ref:`PackedDataContainer` to pack nested arrays and dictionaries. .. rst-class:: classref-reftable-group diff --git a/classes/class_packedfloat32array.rst b/classes/class_packedfloat32array.rst index 25a0e7353..058ddecdf 100644 --- a/classes/class_packedfloat32array.rst +++ b/classes/class_packedfloat32array.rst @@ -187,6 +187,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -211,6 +213,8 @@ Clears the array. This is equivalent to using :ref:`resize` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -247,6 +251,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -259,6 +265,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -343,6 +351,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -395,6 +405,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_packedfloat64array.rst b/classes/class_packedfloat64array.rst index e20c348b8..9508a7741 100644 --- a/classes/class_packedfloat64array.rst +++ b/classes/class_packedfloat64array.rst @@ -187,6 +187,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -211,6 +213,8 @@ Clears the array. This is equivalent to using :ref:`resize` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -247,6 +251,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -259,6 +265,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -343,6 +351,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -395,6 +405,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_packedvector2array.rst b/classes/class_packedvector2array.rst index 6b12d0dea..3d06b7db7 100644 --- a/classes/class_packedvector2array.rst +++ b/classes/class_packedvector2array.rst @@ -194,6 +194,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -218,6 +220,8 @@ Clears the array. This is equivalent to using :ref:`resize` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -254,6 +258,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -266,6 +272,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -350,6 +358,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -402,6 +412,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_packedvector3array.rst b/classes/class_packedvector3array.rst index ffab2044b..0889a5bd1 100644 --- a/classes/class_packedvector3array.rst +++ b/classes/class_packedvector3array.rst @@ -187,6 +187,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -211,6 +213,8 @@ Clears the array. This is equivalent to using :ref:`resize` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -247,6 +251,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -259,6 +265,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -343,6 +351,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -395,6 +405,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_panel.rst b/classes/class_panel.rst index 1beccabaa..8b98d0ab3 100644 --- a/classes/class_panel.rst +++ b/classes/class_panel.rst @@ -12,14 +12,14 @@ Panel **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Provides an opaque background for :ref:`Control` children. +A GUI control that displays a :ref:`StyleBox`. .. rst-class:: classref-introduction-group Description ----------- -Panel is a :ref:`Control` that displays an opaque background. It's commonly used as a parent and container for other types of :ref:`Control` nodes. +**Panel** is a GUI control that displays a :ref:`StyleBox`. See also :ref:`PanelContainer`. .. rst-class:: classref-introduction-group @@ -59,7 +59,7 @@ Theme Property Descriptions :ref:`StyleBox` **panel** -The style of this **Panel**. +The :ref:`StyleBox` of this control. .. |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_panelcontainer.rst b/classes/class_panelcontainer.rst index 99f1838bb..8876faaf0 100644 --- a/classes/class_panelcontainer.rst +++ b/classes/class_panelcontainer.rst @@ -14,21 +14,21 @@ PanelContainer **Inherited By:** :ref:`ScriptEditor` -Panel container type. +A container that keeps its child controls within the area of a :ref:`StyleBox`. .. rst-class:: classref-introduction-group Description ----------- -Panel container type. This container fits controls inside of the delimited area of a stylebox. It's useful for giving controls an outline. +A container that keeps its child controls within the area of a :ref:`StyleBox`. Useful for giving controls an outline. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` - `2D Role Playing Game Demo `__ diff --git a/classes/class_parallaxlayer.rst b/classes/class_parallaxlayer.rst index 919eca30b..fa37e6c94 100644 --- a/classes/class_parallaxlayer.rst +++ b/classes/class_parallaxlayer.rst @@ -61,9 +61,11 @@ Property Descriptions - void **set_mirroring** **(** :ref:`Vector2` value **)** - :ref:`Vector2` **get_mirroring** **(** **)** -The ParallaxLayer's :ref:`Texture2D` mirroring. Useful for creating an infinite scrolling background. If an axis is set to ``0``, the :ref:`Texture2D` will not be mirrored. +The ParallaxLayer's :ref:`Texture2D` repeating. Useful for creating an infinite scrolling background. If an axis is set to ``0``, the :ref:`Texture2D` will not be repeated. -If the length of the viewport axis is bigger than twice the mirrored axis size, it will not repeat infinitely, as the parallax layer only draws 2 instances of the texture at any one time. +If the length of the viewport axis is bigger than twice the repeated axis size, it will not repeat infinitely, as the parallax layer only draws 2 instances of the texture at any given time. + +\ **Note:** Despite its name, the texture will not be mirrored, it will simply be repeated. .. rst-class:: classref-item-separator diff --git a/classes/class_physicalbone2d.rst b/classes/class_physicalbone2d.rst index ffcd7ca18..b37a16cbe 100644 --- a/classes/class_physicalbone2d.rst +++ b/classes/class_physicalbone2d.rst @@ -12,18 +12,18 @@ PhysicalBone2D **Inherits:** :ref:`RigidBody2D` **<** :ref:`PhysicsBody2D` **<** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -A 2D node that can be used for physically aware bones in 2D. +A :ref:`RigidBody2D`-derived node used to make :ref:`Bone2D`\ s in a :ref:`Skeleton2D` react to physics. .. rst-class:: classref-introduction-group Description ----------- -The ``PhysicalBone2D`` node is a :ref:`RigidBody2D`-based node that can be used to make :ref:`Bone2D` nodes in a :ref:`Skeleton2D` react to physics. This node is very similar to the :ref:`PhysicalBone3D` node, just for 2D instead of 3D. +The **PhysicalBone2D** node is a :ref:`RigidBody2D`-based node that can be used to make :ref:`Bone2D`\ s in a :ref:`Skeleton2D` react to physics. -\ **Note:** To have the Bone2D nodes visually follow the ``PhysicalBone2D`` node, use a :ref:`SkeletonModification2DPhysicalBones` modification on the :ref:`Skeleton2D` node with the :ref:`Bone2D` nodes. +\ **Note:** To make the :ref:`Bone2D`\ s visually follow the **PhysicalBone2D** node, use a :ref:`SkeletonModification2DPhysicalBones` modification on the :ref:`Skeleton2D` parent. -\ **Note:** The PhysicalBone2D node does not automatically create a :ref:`Joint2D` node to keep ``PhysicalBone2D`` nodes together. You will need to create these manually. For most cases, you want to use a :ref:`PinJoint2D` node. The ``PhysicalBone2D`` node can automatically configure the :ref:`Joint2D` node once it's been created as a child node. +\ **Note:** The **PhysicalBone2D** node does not automatically create a :ref:`Joint2D` node to keep **PhysicalBone2D** nodes together. They must be created manually. For most cases, you want to use a :ref:`PinJoint2D` node. The **PhysicalBone2D** node will automatically configure the :ref:`Joint2D` node once it's been added as a child node. .. rst-class:: classref-reftable-group @@ -79,7 +79,7 @@ Property Descriptions - void **set_auto_configure_joint** **(** :ref:`bool` value **)** - :ref:`bool` **get_auto_configure_joint** **(** **)** -If ``true``, the ``PhysicalBone2D`` node will automatically configure the first :ref:`Joint2D` child node. The automatic configuration is limited to setting up the node properties and positioning the :ref:`Joint2D`. +If ``true``, the **PhysicalBone2D** will automatically configure the first :ref:`Joint2D` child node. The automatic configuration is limited to setting up the node properties and positioning the :ref:`Joint2D`. .. rst-class:: classref-item-separator @@ -96,7 +96,7 @@ If ``true``, the ``PhysicalBone2D`` node will automatically configure the first - void **set_bone2d_index** **(** :ref:`int` value **)** - :ref:`int` **get_bone2d_index** **(** **)** -The index of the :ref:`Bone2D` node that this ``PhysicalBone2D`` node is supposed to be simulating. +The index of the :ref:`Bone2D` that this **PhysicalBone2D** should simulate. .. rst-class:: classref-item-separator @@ -113,7 +113,7 @@ The index of the :ref:`Bone2D` node that this ``PhysicalBone2D`` n - void **set_bone2d_nodepath** **(** :ref:`NodePath` value **)** - :ref:`NodePath` **get_bone2d_nodepath** **(** **)** -The :ref:`NodePath` to the :ref:`Bone2D` node that this ``PhysicalBone2D`` node is supposed to be simulating. +The :ref:`NodePath` to the :ref:`Bone2D` that this **PhysicalBone2D** isshould simulate. .. rst-class:: classref-item-separator @@ -130,7 +130,7 @@ The :ref:`NodePath` to the :ref:`Bone2D` node that - void **set_follow_bone_when_simulating** **(** :ref:`bool` value **)** - :ref:`bool` **get_follow_bone_when_simulating** **(** **)** -If ``true``, the ``PhysicalBone2D`` will keep the transform of the bone it is bound to when simulating physics. +If ``true``, the **PhysicalBone2D** will keep the transform of the bone it is bound to when simulating physics. .. rst-class:: classref-item-separator @@ -147,9 +147,9 @@ If ``true``, the ``PhysicalBone2D`` will keep the transform of the bone it is bo - void **set_simulate_physics** **(** :ref:`bool` value **)** - :ref:`bool` **get_simulate_physics** **(** **)** -If ``true``, the ``PhysicalBone2D`` will start simulating using physics. If ``false``, the ``PhysicalBone2D`` will follow the transform of the :ref:`Bone2D` node. +If ``true``, the **PhysicalBone2D** will start simulating using physics. If ``false``, the **PhysicalBone2D** will follow the transform of the :ref:`Bone2D` node. -\ **Note:** To have the Bone2D nodes visually follow the ``PhysicalBone2D`` node, use a :ref:`SkeletonModification2DPhysicalBones` modification on the :ref:`Skeleton2D` node with the :ref:`Bone2D` nodes. +\ **Note:** To have the :ref:`Bone2D`\ s visually follow the **PhysicalBone2D**, use a :ref:`SkeletonModification2DPhysicalBones` modification on the :ref:`Skeleton2D` node with the :ref:`Bone2D` nodes. .. rst-class:: classref-section-separator @@ -166,7 +166,7 @@ Method Descriptions :ref:`Joint2D` **get_joint** **(** **)** |const| -Returns the first :ref:`Joint2D` child node, if one exists. This is mainly a helper function to make it easier to get the :ref:`Joint2D` that the ``PhysicalBone2D`` is autoconfiguring. +Returns the first :ref:`Joint2D` child node, if one exists. This is mainly a helper function to make it easier to get the :ref:`Joint2D` that the **PhysicalBone2D** is autoconfiguring. .. rst-class:: classref-item-separator @@ -178,7 +178,7 @@ Returns the first :ref:`Joint2D` child node, if one exists. This :ref:`bool` **is_simulating_physics** **(** **)** |const| -Returns a boolean that indicates whether the ``PhysicalBone2D`` node is running and simulating using the Godot 2D physics engine. When ``true``, the PhysicalBone2D node is using physics. +Returns a boolean that indicates whether the **PhysicalBone2D** is running and simulating using the Godot 2D physics engine. When ``true``, the PhysicalBone2D node is using physics. .. |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_physicalbone3d.rst b/classes/class_physicalbone3d.rst index 3a32ecd65..a390858ab 100644 --- a/classes/class_physicalbone3d.rst +++ b/classes/class_physicalbone3d.rst @@ -12,12 +12,14 @@ PhysicalBone3D **Inherits:** :ref:`PhysicsBody3D` **<** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` +A physics body used to make bones in a :ref:`Skeleton3D` react to physics. + .. rst-class:: classref-introduction-group Description ----------- -**Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +The **PhysicalBone3D** node is a physics body that can be used to make bones in a :ref:`Skeleton3D` react to physics. .. rst-class:: classref-reftable-group diff --git a/classes/class_plane.rst b/classes/class_plane.rst index 6476171e5..b77d47089 100644 --- a/classes/class_plane.rst +++ b/classes/class_plane.rst @@ -10,14 +10,14 @@ Plane ===== -Plane in hessian form. +A plane in Hessian normal form. .. rst-class:: classref-introduction-group Description ----------- -Plane represents a normalized plane equation. Basically, "normal" is the normal of the plane (a,b,c normalized), and "d" is the distance from the origin to the plane (in the direction of "normal"). "Over" or "Above" the plane is considered the side of the plane towards where the normal is pointing. +Represents a normalized plane equation. :ref:`normal` is the normal of the plane (a, b, c normalized), and :ref:`d` is the distance from the origin to the plane (in the direction of "normal"). "Over" or "Above" the plane is considered the side of the plane towards where the normal is pointing. .. rst-class:: classref-introduction-group diff --git a/classes/class_polygon2d.rst b/classes/class_polygon2d.rst index 2010ab649..874212455 100644 --- a/classes/class_polygon2d.rst +++ b/classes/class_polygon2d.rst @@ -438,7 +438,7 @@ Returns the path to the node associated with the specified bone. :ref:`PackedFloat32Array` **get_bone_weights** **(** :ref:`int` index **)** |const| -Returns the height values of the specified bone. +Returns the weight values of the specified bone. .. rst-class:: classref-item-separator diff --git a/classes/class_popup.rst b/classes/class_popup.rst index f2e4c2f25..728d3d7ff 100644 --- a/classes/class_popup.rst +++ b/classes/class_popup.rst @@ -14,14 +14,14 @@ Popup **Inherited By:** :ref:`PopupMenu`, :ref:`PopupPanel` -Popup is a base window container for popup-like subwindows. +Base class for contextual windows and panels with fixed position. .. rst-class:: classref-introduction-group Description ----------- -Popup is a base window container for popup-like subwindows. It's a modal by default (see :ref:`Window.popup_window`) and has helpers for custom popup behavior. +**Popup** is a base class for contextual windows and panels with fixed position. It's a modal by default (see :ref:`Window.popup_window`) and provides methods for implementing custom popup behavior. .. rst-class:: classref-reftable-group diff --git a/classes/class_popupmenu.rst b/classes/class_popupmenu.rst index 69a93002c..63e833907 100644 --- a/classes/class_popupmenu.rst +++ b/classes/class_popupmenu.rst @@ -12,23 +12,23 @@ PopupMenu **Inherits:** :ref:`Popup` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -PopupMenu displays a list of options. +A modal window used to display a list of options. .. rst-class:: classref-introduction-group Description ----------- -**PopupMenu** is a modal window used to display a list of options. They are popular in toolbars or context menus. +**PopupMenu** is a modal window used to display a list of options. Useful for toolbars and context menus. -The size of a **PopupMenu** can be limited by using :ref:`Window.max_size`. If the height of the list of items is larger than the maximum height of the **PopupMenu**, a :ref:`ScrollContainer` within the popup will allow the user to scroll the contents. +The size of a **PopupMenu** can be limited by using :ref:`Window.max_size`. If the height of the list of items is larger than the maximum height of the **PopupMenu**, a :ref:`ScrollContainer` within the popup will allow the user to scroll the contents. If no maximum size is set, or if it is set to ``0``, the **PopupMenu** height will be limited by its parent rect. -If no maximum size is set, or if it is set to 0, the **PopupMenu** height will be limited by its parent rect. - -All ``set_*`` methods allow negative item index, which makes the item accessed from the last one. +All ``set_*`` methods allow negative item indices, i.e. ``-1`` to access the last item, ``-2`` to select the second-to-last item, and so on. \ **Incremental search:** Like :ref:`ItemList` and :ref:`Tree`, **PopupMenu** supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing :ref:`ProjectSettings.gui/timers/incremental_search_max_interval_msec`. +\ **Note:** The ID values used for items are limited to 32 bits, not full 64 bits of :ref:`int`. This has a range of ``-2^32`` to ``2^32 - 1``, i.e. ``-2147483648`` to ``2147483647``. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_popuppanel.rst b/classes/class_popuppanel.rst index 778974fea..9cba6f2d8 100644 --- a/classes/class_popuppanel.rst +++ b/classes/class_popuppanel.rst @@ -12,16 +12,14 @@ PopupPanel **Inherits:** :ref:`Popup` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -Class for displaying popups with a panel background. +A popup with a panel background. .. rst-class:: classref-introduction-group Description ----------- -Class for displaying popups with a panel background. In some cases it might be simpler to use than :ref:`Popup`, since it provides a configurable background. If you are making windows, better check :ref:`Window`. - -If any :ref:`Control` node is added as a child of this **PopupPanel**, it will be stretched to fit the panel's size (similar to how :ref:`PanelContainer` works). +A popup with a configurable panel background. Any child controls added to this node will be stretched to fit the panel's size (similar to how :ref:`PanelContainer` works). If you are making windows, see :ref:`Window`. .. rst-class:: classref-reftable-group diff --git a/classes/class_progressbar.rst b/classes/class_progressbar.rst index 18aecfbfa..a88846e67 100644 --- a/classes/class_progressbar.rst +++ b/classes/class_progressbar.rst @@ -12,14 +12,14 @@ ProgressBar **Inherits:** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -General-purpose progress bar. +A control used for visual representation of a percentage. .. rst-class:: classref-introduction-group Description ----------- -General-purpose progress bar. Shows fill percentage from right to left. +A control used for visual representation of a percentage. Shows fill percentage from right to left. .. rst-class:: classref-reftable-group diff --git a/classes/class_projection.rst b/classes/class_projection.rst index 3f77dfdf2..c8560450a 100644 --- a/classes/class_projection.rst +++ b/classes/class_projection.rst @@ -10,7 +10,7 @@ Projection ========== -3D projection (4x4 matrix). +A 4×4 matrix for 3D projective transformations. .. rst-class:: classref-introduction-group @@ -19,7 +19,7 @@ Description A 4x4 matrix used for 3D projective transformations. It can represent transformations such as translation, rotation, scaling, shearing, and perspective division. It consists of four :ref:`Vector4` columns. -For purely linear transformations (translation, rotation, and scale), it is recommended to use :ref:`Transform3D`, as it is more performant and has a lower memory footprint. +For purely linear transformations (translation, rotation, and scale), it is recommended to use :ref:`Transform3D`, as it is more performant and requires less memory. Used internally as :ref:`Camera3D`'s projection matrix. diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 191efb5ef..c3149b5a6 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -12,14 +12,14 @@ ProjectSettings **Inherits:** :ref:`Object` -Contains global variables accessible from everywhere. +Stores globally-accessible variables. .. rst-class:: classref-introduction-group Description ----------- -Contains global variables accessible from everywhere. Use :ref:`get_setting`, :ref:`set_setting` or :ref:`has_setting` to access them. Variables stored in ``project.godot`` are also loaded into ProjectSettings, making this object very useful for reading custom game configuration options. +Stores variables that can be accessed from everywhere. Use :ref:`get_setting`, :ref:`set_setting` or :ref:`has_setting` to access them. Variables stored in ``project.godot`` are also loaded into **ProjectSettings**, making this object very useful for reading custom game configuration options. When naming a Project Settings property, use the full path to the setting including the category. For example, ``"application/config/name"`` for the project name. Category and property names can be viewed in the Project Settings dialog. @@ -3315,9 +3315,13 @@ On desktop platforms, overrides the game's initial window width. See also :ref:` :ref:`String` **display/window/stretch/mode** = ``"disabled"`` -.. container:: contribute +Defines how the base size is stretched to fit the resolution of the window or screen. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **"disabled"**: No stretching happens. One unit in the scene corresponds to one pixel on the screen. In this mode, :ref:`display/window/stretch/aspect` has no effect. Recommended for non-game applications. + +\ **"canvas_items"**: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking :ref:`display/window/stretch/aspect` into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art aesthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). + +\ **"viewport"**: The size of the root :ref:`Viewport` is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking :ref:`display/window/stretch/aspect` into account). Recommended for games that use a pixel art aesthetic. .. rst-class:: classref-item-separator @@ -9781,7 +9785,7 @@ If ``true``, the texture importer will import lossless textures using the PNG fo :ref:`bool` **rendering/textures/vram_compression/import_etc2_astc** -If ``true``, the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normalmaps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4x4 block size). +If ``true``, the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normal maps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4x4 block size). \ **Note:** Changing this setting does *not* impact textures that were already imported before. To make this setting apply to textures that were already imported, exit the editor, remove the ``.godot/imported/`` folder located inside the project folder then restart the editor (see :ref:`application/config/use_hidden_project_data_directory`). @@ -10027,11 +10031,11 @@ void **add_property_info** **(** :ref:`Dictionary` hint **)** Adds a custom property info to a property. The dictionary must contain: -- ``name``: :ref:`String` (the property's name) +- ``"name"``: :ref:`String` (the property's name) -- ``type``: :ref:`int` (see :ref:`Variant.Type`) +- ``"type"``: :ref:`int` (see :ref:`Variant.Type`) -- optionally ``hint``: :ref:`int` (see :ref:`PropertyHint`) and ``hint_string``: :ref:`String`\ +- optionally ``"hint"``: :ref:`int` (see :ref:`PropertyHint`) and ``"hint_string"``: :ref:`String`\ \ **Example:**\ diff --git a/classes/class_randomnumbergenerator.rst b/classes/class_randomnumbergenerator.rst index 35ba2afb5..73f2b4895 100644 --- a/classes/class_randomnumbergenerator.rst +++ b/classes/class_randomnumbergenerator.rst @@ -12,7 +12,7 @@ RandomNumberGenerator **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A class for generating pseudo-random numbers. +Provides methods for generating pseudo-random numbers. .. rst-class:: classref-introduction-group @@ -21,7 +21,7 @@ Description RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses `PCG32 `__. -\ **Note:** The underlying algorithm is an implementation detail. As a result, it should not be depended upon for reproducible random streams across Godot versions. +\ **Note:** The underlying algorithm is an implementation detail and should not be depended upon. To generate a random float number (within a given range) based on a time-dependant seed: @@ -31,8 +31,6 @@ To generate a random float number (within a given range) based on a time-dependa func _ready(): var my_random_number = rng.randf_range(-10.0, 10.0) -\ **Note:** The default values of :ref:`seed` and :ref:`state` properties are pseudo-random, and change when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. - .. rst-class:: classref-introduction-group Tutorials @@ -102,6 +100,8 @@ Initializes the random number generator state based on the given seed value. A g \ **Note:** Setting this property produces a side effect of changing the internal :ref:`state`, so make sure to initialize the seed *before* modifying the :ref:`state`: +\ **Note:** The default value of this property is pseudo-random, and changes when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. + :: var rng = RandomNumberGenerator.new() @@ -136,6 +136,8 @@ The current state of the random number generator. Save and restore this property \ **Note:** Do not set state to arbitrary values, since the random number generator requires the state to have certain qualities to behave properly. It should only be set to values that came from the state property itself. To initialize the random number generator with arbitrary input, use :ref:`seed` instead. +\ **Note:** The default value of this property is pseudo-random, and changes when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. + .. rst-class:: classref-section-separator ---- diff --git a/classes/class_range.rst b/classes/class_range.rst index 2a6bd4503..d535a242b 100644 --- a/classes/class_range.rst +++ b/classes/class_range.rst @@ -14,14 +14,14 @@ Range **Inherited By:** :ref:`EditorSpinSlider`, :ref:`ProgressBar`, :ref:`ScrollBar`, :ref:`Slider`, :ref:`SpinBox`, :ref:`TextureProgressBar` -Abstract base class for range-based controls. +Abstract base class for controls that represent a number within a range. .. rst-class:: classref-introduction-group Description ----------- -Range is a base class for :ref:`Control` nodes that change a floating-point :ref:`value` between a :ref:`min_value` and :ref:`max_value`, using a configured :ref:`step` and :ref:`page` size. See e.g. :ref:`ScrollBar` and :ref:`Slider` for examples of higher level nodes using Range. +Range is an abstract base class for controls that represent a number within a range, using a configured :ref:`step` and :ref:`page` size. See e.g. :ref:`ScrollBar` and :ref:`Slider` for examples of higher-level nodes using Range. .. rst-class:: classref-reftable-group @@ -158,7 +158,7 @@ If ``true``, :ref:`value` may be less than :ref:`min - void **set_exp_ratio** **(** :ref:`bool` value **)** - :ref:`bool` **is_ratio_exp** **(** **)** -If ``true``, and ``min_value`` is greater than 0, ``value`` will be represented exponentially rather than linearly. +If ``true``, and :ref:`min_value` is greater than 0, :ref:`value` will be represented exponentially rather than linearly. .. rst-class:: classref-item-separator @@ -175,7 +175,7 @@ If ``true``, and ``min_value`` is greater than 0, ``value`` will be represented - void **set_max** **(** :ref:`float` value **)** - :ref:`float` **get_max** **(** **)** -Maximum value. Range is clamped if ``value`` is greater than ``max_value``. +Maximum value. Range is clamped if :ref:`value` is greater than :ref:`max_value`. .. rst-class:: classref-item-separator @@ -192,7 +192,7 @@ Maximum value. Range is clamped if ``value`` is greater than ``max_value``. - void **set_min** **(** :ref:`float` value **)** - :ref:`float` **get_min** **(** **)** -Minimum value. Range is clamped if ``value`` is less than ``min_value``. +Minimum value. Range is clamped if :ref:`value` is less than :ref:`min_value`. .. rst-class:: classref-item-separator @@ -209,7 +209,7 @@ Minimum value. Range is clamped if ``value`` is less than ``min_value``. - void **set_page** **(** :ref:`float` value **)** - :ref:`float` **get_page** **(** **)** -Page size. Used mainly for :ref:`ScrollBar`. ScrollBar's length is its size multiplied by ``page`` over the difference between ``min_value`` and ``max_value``. +Page size. Used mainly for :ref:`ScrollBar`. ScrollBar's length is its size multiplied by :ref:`page` over the difference between :ref:`min_value` and :ref:`max_value`. .. rst-class:: classref-item-separator @@ -243,7 +243,7 @@ The value mapped between 0 and 1. - void **set_use_rounded_values** **(** :ref:`bool` value **)** - :ref:`bool` **is_using_rounded_values** **(** **)** -If ``true``, ``value`` will always be rounded to the nearest integer. +If ``true``, :ref:`value` will always be rounded to the nearest integer. .. rst-class:: classref-item-separator @@ -260,7 +260,7 @@ If ``true``, ``value`` will always be rounded to the nearest integer. - void **set_step** **(** :ref:`float` value **)** - :ref:`float` **get_step** **(** **)** -If greater than 0, ``value`` will always be rounded to a multiple of ``step``. If ``rounded`` is also ``true``, ``value`` will first be rounded to a multiple of ``step`` then rounded to the nearest integer. +If greater than 0, :ref:`value` will always be rounded to a multiple of this property's value. If :ref:`rounded` is also ``true``, :ref:`value` will first be rounded to a multiple of this property's value, then rounded to the nearest integer. .. rst-class:: classref-item-separator diff --git a/classes/class_rect2.rst b/classes/class_rect2.rst index 282447dd8..c9dd68977 100644 --- a/classes/class_rect2.rst +++ b/classes/class_rect2.rst @@ -10,7 +10,7 @@ Rect2 ===== -2D axis-aligned bounding box using floating point coordinates. +A 2D axis-aligned bounding box using floating-point coordinates. .. rst-class:: classref-introduction-group diff --git a/classes/class_rect2i.rst b/classes/class_rect2i.rst index f8a1fca62..feafe49b1 100644 --- a/classes/class_rect2i.rst +++ b/classes/class_rect2i.rst @@ -10,7 +10,7 @@ Rect2i ====== -2D axis-aligned bounding box using integer coordinates. +A 2D axis-aligned bounding box using integer coordinates. .. rst-class:: classref-introduction-group diff --git a/classes/class_referencerect.rst b/classes/class_referencerect.rst index 383702406..7ed680a9f 100644 --- a/classes/class_referencerect.rst +++ b/classes/class_referencerect.rst @@ -12,14 +12,14 @@ ReferenceRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Reference frame for GUI. +A rectangle hint for designing UIs. .. rst-class:: classref-introduction-group Description ----------- -A rectangle box that displays only a :ref:`border_color` border color around its rectangle. **ReferenceRect** has no fill :ref:`Color`. If you need to display a rectangle filled with a solid color, consider using :ref:`ColorRect` instead. +A rectangle box that displays only a colored border around its rectangle. It is used to visualize the extents of a :ref:`Control`. .. rst-class:: classref-reftable-group @@ -57,7 +57,7 @@ Property Descriptions - void **set_border_color** **(** :ref:`Color` value **)** - :ref:`Color` **get_border_color** **(** **)** -Sets the border :ref:`Color` of the **ReferenceRect**. +Sets the border color of the **ReferenceRect**. .. rst-class:: classref-item-separator diff --git a/classes/class_renderingdevice.rst b/classes/class_renderingdevice.rst index 9c0159163..1ac726825 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -3681,7 +3681,7 @@ enum **InitialAction**: :ref:`InitialAction` **INITIAL_ACTION_CLEAR** = ``0`` - +Start rendering and clear the whole framebuffer. .. _class_RenderingDevice_constant_INITIAL_ACTION_CLEAR_REGION: @@ -3689,7 +3689,7 @@ enum **InitialAction**: :ref:`InitialAction` **INITIAL_ACTION_CLEAR_REGION** = ``1`` - +Start rendering and clear the framebuffer in the specified region. .. _class_RenderingDevice_constant_INITIAL_ACTION_CLEAR_REGION_CONTINUE: @@ -3697,7 +3697,7 @@ enum **InitialAction**: :ref:`InitialAction` **INITIAL_ACTION_CLEAR_REGION_CONTINUE** = ``2`` - +Continue rendering and clear the framebuffer in the specified region. Framebuffer must have been left in :ref:`FINAL_ACTION_CONTINUE` state as the final action previously. .. _class_RenderingDevice_constant_INITIAL_ACTION_KEEP: @@ -3705,7 +3705,7 @@ enum **InitialAction**: :ref:`InitialAction` **INITIAL_ACTION_KEEP** = ``3`` - +Start rendering, but keep attached color texture contents. If the framebuffer was previously used to read in a shader, this will automatically insert a layout transition. .. _class_RenderingDevice_constant_INITIAL_ACTION_DROP: @@ -3713,7 +3713,7 @@ enum **InitialAction**: :ref:`InitialAction` **INITIAL_ACTION_DROP** = ``4`` - +Start rendering, ignore what is there; write above it. In general, this is the fastest option when you will be writing every single pixel and you don't need a clear color. .. _class_RenderingDevice_constant_INITIAL_ACTION_CONTINUE: @@ -3721,7 +3721,7 @@ enum **InitialAction**: :ref:`InitialAction` **INITIAL_ACTION_CONTINUE** = ``5`` - +Continue rendering. Framebuffer must have been left in :ref:`FINAL_ACTION_CONTINUE` state as the final action previously. .. _class_RenderingDevice_constant_INITIAL_ACTION_MAX: diff --git a/classes/class_renderingserver.rst b/classes/class_renderingserver.rst index e0e11d510..122a58551 100644 --- a/classes/class_renderingserver.rst +++ b/classes/class_renderingserver.rst @@ -1212,7 +1212,7 @@ Array is a vertex color array. :ref:`ArrayType` **ARRAY_TEX_UV** = ``4`` -Array is an UV coordinates array. +Array is a UV coordinates array. .. _class_RenderingServer_constant_ARRAY_TEX_UV2: @@ -1220,7 +1220,7 @@ Array is an UV coordinates array. :ref:`ArrayType` **ARRAY_TEX_UV2** = ``5`` -Array is an UV coordinates array for the second set of UV coordinates. +Array is a UV coordinates array for the second set of UV coordinates. .. _class_RenderingServer_constant_ARRAY_CUSTOM0: @@ -1416,7 +1416,7 @@ Flag used to mark a vertex color array. :ref:`ArrayFormat` **ARRAY_FORMAT_TEX_UV** = ``16`` -Flag used to mark an UV coordinates array. +Flag used to mark a UV coordinates array. .. _class_RenderingServer_constant_ARRAY_FORMAT_TEX_UV2: @@ -1424,7 +1424,7 @@ Flag used to mark an UV coordinates array. :ref:`ArrayFormat` **ARRAY_FORMAT_TEX_UV2** = ``32`` -Flag used to mark an UV coordinates array for the second UV coordinates. +Flag used to mark a UV coordinates array for the second UV coordinates. .. _class_RenderingServer_constant_ARRAY_FORMAT_CUSTOM0: diff --git a/classes/class_resource.rst b/classes/class_resource.rst index 22ec3a4ed..a27238cbe 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -14,7 +14,7 @@ Resource **Inherited By:** :ref:`Animation`, :ref:`AnimationLibrary`, :ref:`AnimationNode`, :ref:`AnimationNodeStateMachinePlayback`, :ref:`AnimationNodeStateMachineTransition`, :ref:`AudioBusLayout`, :ref:`AudioEffect`, :ref:`AudioStream`, :ref:`BitMap`, :ref:`BoneMap`, :ref:`ButtonGroup`, :ref:`CameraAttributes`, :ref:`CryptoKey`, :ref:`Curve`, :ref:`Curve2D`, :ref:`Curve3D`, :ref:`EditorNode3DGizmoPlugin`, :ref:`EditorSettings`, :ref:`Environment`, :ref:`Font`, :ref:`GDExtension`, :ref:`GLTFAccessor`, :ref:`GLTFAnimation`, :ref:`GLTFBufferView`, :ref:`GLTFCamera`, :ref:`GLTFDocument`, :ref:`GLTFDocumentExtension`, :ref:`GLTFLight`, :ref:`GLTFMesh`, :ref:`GLTFNode`, :ref:`GLTFSkeleton`, :ref:`GLTFSkin`, :ref:`GLTFSpecGloss`, :ref:`GLTFState`, :ref:`GLTFTexture`, :ref:`GLTFTextureSampler`, :ref:`Gradient`, :ref:`Image`, :ref:`ImporterMesh`, :ref:`InputEvent`, :ref:`JSON`, :ref:`LabelSettings`, :ref:`LightmapGIData`, :ref:`Material`, :ref:`Mesh`, :ref:`MeshLibrary`, :ref:`MissingResource`, :ref:`MultiMesh`, :ref:`NavigationMesh`, :ref:`NavigationPolygon`, :ref:`Noise`, :ref:`Occluder3D`, :ref:`OccluderPolygon2D`, :ref:`OggPacketSequence`, :ref:`OpenXRAction`, :ref:`OpenXRActionMap`, :ref:`OpenXRActionSet`, :ref:`OpenXRInteractionProfile`, :ref:`OpenXRIPBinding`, :ref:`PackedDataContainer`, :ref:`PackedScene`, :ref:`PhysicsMaterial`, :ref:`PolygonPathFinder`, :ref:`RDShaderFile`, :ref:`RDShaderSPIRV`, :ref:`RichTextEffect`, :ref:`SceneReplicationConfig`, :ref:`Script`, :ref:`Shader`, :ref:`ShaderInclude`, :ref:`Shape2D`, :ref:`Shape3D`, :ref:`Shortcut`, :ref:`SkeletonModification2D`, :ref:`SkeletonModificationStack2D`, :ref:`SkeletonProfile`, :ref:`Skin`, :ref:`Sky`, :ref:`SpriteFrames`, :ref:`StyleBox`, :ref:`SyntaxHighlighter`, :ref:`Texture`, :ref:`Theme`, :ref:`TileMapPattern`, :ref:`TileSet`, :ref:`TileSetSource`, :ref:`Translation`, :ref:`VideoStream`, :ref:`VideoStreamPlayback`, :ref:`VisualShaderNode`, :ref:`VoxelGIData`, :ref:`World2D`, :ref:`World3D`, :ref:`X509Certificate` -Base class for all resources. +Base class for serializable objects. .. rst-class:: classref-introduction-group @@ -163,7 +163,7 @@ An optional name for this resource. When defined, its value is displayed to repr - void **set_path** **(** :ref:`String` value **)** - :ref:`String` **get_path** **(** **)** -The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the :ref:`PackedScene`'s filepath, followed by an unique identifier. +The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the :ref:`PackedScene`'s filepath, followed by a unique identifier. \ **Note:** Setting this property manually may fail if a resource with the same path has already been previously loaded. If necessary, use :ref:`take_over_path`. diff --git a/classes/class_resourceimporter.rst b/classes/class_resourceimporter.rst index 8877cede2..25bd51710 100644 --- a/classes/class_resourceimporter.rst +++ b/classes/class_resourceimporter.rst @@ -14,14 +14,14 @@ ResourceImporter **Inherited By:** :ref:`EditorImportPlugin` -Base class for the implementation of core resource importers. +Base class for resource importers. .. rst-class:: classref-introduction-group Description ----------- -This is the base class for the resource importers implemented in core. To implement your own resource importers using editor plugins, see :ref:`EditorImportPlugin`. +This is the base class for Godot's resource importers. To implement your own resource importers using editor plugins, see :ref:`EditorImportPlugin`. .. rst-class:: classref-introduction-group diff --git a/classes/class_resourceloader.rst b/classes/class_resourceloader.rst index 94d2d0315..ccc91a62f 100644 --- a/classes/class_resourceloader.rst +++ b/classes/class_resourceloader.rst @@ -12,14 +12,14 @@ ResourceLoader **Inherits:** :ref:`Object` -Singleton used to load resource files. +A singleton for loading resource files. .. rst-class:: classref-introduction-group Description ----------- -Singleton used to load resource files from the filesystem. +A singleton used to load resource files from the filesystem. It uses the many :ref:`ResourceFormatLoader` classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine. diff --git a/classes/class_resourcepreloader.rst b/classes/class_resourcepreloader.rst index 6af4f205d..344aa7eec 100644 --- a/classes/class_resourcepreloader.rst +++ b/classes/class_resourcepreloader.rst @@ -12,7 +12,7 @@ ResourcePreloader **Inherits:** :ref:`Node` **<** :ref:`Object` -Preloads a list of resources inside a scene. +A node used to preload sub-resources inside a scene. .. rst-class:: classref-introduction-group diff --git a/classes/class_resourcesaver.rst b/classes/class_resourcesaver.rst index b50eadd52..5f9a6552e 100644 --- a/classes/class_resourcesaver.rst +++ b/classes/class_resourcesaver.rst @@ -12,16 +12,16 @@ ResourceSaver **Inherits:** :ref:`Object` -Singleton for saving Godot-specific resource types. +A singleton for saving :ref:`Resource`\ s to the filesystem. .. rst-class:: classref-introduction-group Description ----------- -Singleton for saving Godot-specific resource types to the filesystem. +A singleton for saving resource types to the filesystem. -It uses the many :ref:`ResourceFormatSaver` classes registered in the engine (either built-in or from a plugin) to save engine-specific resource data to text-based (e.g. ``.tres`` or ``.tscn``) or binary files (e.g. ``.res`` or ``.scn``). +It uses the many :ref:`ResourceFormatSaver` classes registered in the engine (either built-in or from a plugin) to save resource data to text-based (e.g. ``.tres`` or ``.tscn``) or binary files (e.g. ``.res`` or ``.scn``). .. rst-class:: classref-reftable-group diff --git a/classes/class_resourceuid.rst b/classes/class_resourceuid.rst index d96480144..ce4510e7d 100644 --- a/classes/class_resourceuid.rst +++ b/classes/class_resourceuid.rst @@ -12,18 +12,16 @@ ResourceUID **Inherits:** :ref:`Object` -Singleton for managing a cache of resource UIDs within a project. +A singleton that manages the unique identifiers of all resources within a project. .. rst-class:: classref-introduction-group Description ----------- -Resources can not only be referenced using their resource paths ``res://``, but alternatively through a unique identifier specified via ``uid://``. +Resource UIDs (Unique IDentifiers) allow the engine to keep references between resources intact, even if files can renamed or moved. They can be accessed with ``uid://``. -Using UIDs allows for the engine to keep references between resources intact, even if the files get renamed or moved. - -This singleton is responsible for keeping track of all registered resource UIDs of a project, generating new UIDs and converting between the string and integer representation. +\ **ResourceUID** keeps track of all registered resource UIDs in a project, generates new UIDs, and converts between their string and integer representations. .. rst-class:: classref-reftable-group diff --git a/classes/class_richtexteffect.rst b/classes/class_richtexteffect.rst index 038b99e0e..8f67b2a48 100644 --- a/classes/class_richtexteffect.rst +++ b/classes/class_richtexteffect.rst @@ -12,14 +12,14 @@ RichTextEffect **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A custom effect for use with :ref:`RichTextLabel`. +A custom effect for a :ref:`RichTextLabel`. .. rst-class:: classref-introduction-group Description ----------- -A custom effect for use with :ref:`RichTextLabel`. +A custom effect for a :ref:`RichTextLabel`. \ **Note:** For a **RichTextEffect** to be usable, a BBCode tag must be defined as a member variable called ``bbcode`` in the script. diff --git a/classes/class_richtextlabel.rst b/classes/class_richtextlabel.rst index 988a4c90c..e0d0f1e32 100644 --- a/classes/class_richtextlabel.rst +++ b/classes/class_richtextlabel.rst @@ -12,22 +12,22 @@ RichTextLabel **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Label that displays rich text. +A control for displaying text that can contain different font styles, images, and basic formatting. .. rst-class:: classref-introduction-group Description ----------- -Rich text can contain custom text, fonts, images and some basic formatting. The label manages these as an internal tag stack. It also adapts itself to given width/heights. +A control for displaying text that can contain custom fonts, images, and basic formatting. **RichTextLabel** manages these as an internal tag stack. It also adapts itself to given width/heights. \ **Note:** Assignments to :ref:`text` clear the tag stack and reconstruct it from the property's contents. Any edits made to :ref:`text` will erase previous edits made from other manual sources such as :ref:`append_text` and the ``push_*`` / :ref:`pop` methods. \ **Note:** RichTextLabel doesn't support entangled BBCode tags. For example, instead of using ``[b]bold[i]bold italic[/b]italic[/i]``, use ``[b]bold[i]bold italic[/i][/b][i]italic[/i]``. -\ **Note:** ``push_*/pop`` functions won't affect BBCode. +\ **Note:** ``push_*/pop_*`` functions won't affect BBCode. -\ **Note:** Unlike :ref:`Label`, RichTextLabel doesn't have a *property* to horizontally align text to the center. Instead, enable :ref:`bbcode_enabled` and surround the text in a ``[center]`` tag as follows: ``[center]Example[/center]``. There is currently no built-in way to vertically align text either, but this can be emulated by relying on anchors/containers and the :ref:`fit_content` property. +\ **Note:** Unlike :ref:`Label`, **RichTextLabel** doesn't have a *property* to horizontally align text to the center. Instead, enable :ref:`bbcode_enabled` and surround the text in a ``[center]`` tag as follows: ``[center]Example[/center]``. There is currently no built-in way to vertically align text either, but this can be emulated by relying on anchors/containers and the :ref:`fit_content` property. .. rst-class:: classref-introduction-group diff --git a/classes/class_rid.rst b/classes/class_rid.rst index c188fad98..874fe80e6 100644 --- a/classes/class_rid.rst +++ b/classes/class_rid.rst @@ -10,7 +10,7 @@ RID === -Handle for a :ref:`Resource`'s unique ID. +A handle for a :ref:`Resource`'s unique identifier. .. rst-class:: classref-introduction-group diff --git a/classes/class_scenestate.rst b/classes/class_scenestate.rst index 14afd064a..cc86caaf1 100644 --- a/classes/class_scenestate.rst +++ b/classes/class_scenestate.rst @@ -12,14 +12,14 @@ SceneState **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A script interface to a scene file's data. +Provides access to a scene file's information. .. rst-class:: classref-introduction-group Description ----------- -Maintains a list of resources, nodes, exported, and overridden properties, and built-in scripts associated with a scene. +Maintains a list of resources, nodes, exported and overridden properties, and built-in scripts associated with a scene. They cannot be modified from a **SceneState**, only accessed. Useful for peeking into what a :ref:`PackedScene` contains without instantiating it. This class cannot be instantiated directly, it is retrieved for a given scene as the result of :ref:`PackedScene.get_state`. diff --git a/classes/class_scriptcreatedialog.rst b/classes/class_scriptcreatedialog.rst index 1c3dc6f03..ecc0b90a6 100644 --- a/classes/class_scriptcreatedialog.rst +++ b/classes/class_scriptcreatedialog.rst @@ -12,7 +12,7 @@ ScriptCreateDialog **Inherits:** :ref:`ConfirmationDialog` **<** :ref:`AcceptDialog` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -The Editor's popup dialog for creating new :ref:`Script` files. +Godot editor's popup dialog for creating new :ref:`Script` files. .. rst-class:: classref-introduction-group diff --git a/classes/class_scripteditor.rst b/classes/class_scripteditor.rst index 96aae8b63..ac1eea8ec 100644 --- a/classes/class_scripteditor.rst +++ b/classes/class_scripteditor.rst @@ -19,7 +19,9 @@ Godot editor's script editor. Description ----------- -**Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_script_editor`. +Godot editor's script editor. + +\ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_script_editor`. .. rst-class:: classref-reftable-group diff --git a/classes/class_scripteditorbase.rst b/classes/class_scripteditorbase.rst index dd404e8cd..ad3fd3edc 100644 --- a/classes/class_scripteditorbase.rst +++ b/classes/class_scripteditorbase.rst @@ -19,7 +19,7 @@ Base editor for editing scripts in the :ref:`ScriptEditor`. Description ----------- -Base editor for editing scripts in the :ref:`ScriptEditor`, this does not include documentation items. +Base editor for editing scripts in the :ref:`ScriptEditor`. This does not include documentation items. .. rst-class:: classref-reftable-group diff --git a/classes/class_scrollbar.rst b/classes/class_scrollbar.rst index bbbabb413..3df322157 100644 --- a/classes/class_scrollbar.rst +++ b/classes/class_scrollbar.rst @@ -14,14 +14,14 @@ ScrollBar **Inherited By:** :ref:`HScrollBar`, :ref:`VScrollBar` -Base class for scroll bars. +Abstract base class for scrollbars. .. rst-class:: classref-introduction-group Description ----------- -Scrollbars are a :ref:`Range`-based :ref:`Control`, that display a draggable area (the size of the page). Horizontal (:ref:`HScrollBar`) and Vertical (:ref:`VScrollBar`) versions are available. +Abstract base class for scrollbars, typically used to navigate through content that extends beyond the visible area of a control. Scrollbars are :ref:`Range`-based controls. .. rst-class:: classref-reftable-group diff --git a/classes/class_scrollcontainer.rst b/classes/class_scrollcontainer.rst index ace318aec..63f286e0d 100644 --- a/classes/class_scrollcontainer.rst +++ b/classes/class_scrollcontainer.rst @@ -14,25 +14,21 @@ ScrollContainer **Inherited By:** :ref:`EditorInspector` -A helper node for displaying scrollable elements such as lists. +A container used to provide scrollbars to a child control when needed. .. rst-class:: classref-introduction-group Description ----------- -A ScrollContainer node meant to contain a :ref:`Control` child. - -ScrollContainers will automatically create a scrollbar child (:ref:`HScrollBar`, :ref:`VScrollBar`, or both) when needed and will only draw the Control within the ScrollContainer area. Scrollbars will automatically be drawn at the right (for vertical) or bottom (for horizontal) and will enable dragging to move the viewable Control (and its children) within the ScrollContainer. Scrollbars will also automatically resize the grabber based on the :ref:`Control.custom_minimum_size` of the Control relative to the ScrollContainer. - -Works great with a :ref:`Panel` control. You can set :ref:`Control.SIZE_EXPAND` on the children's size flags, so they will upscale to the ScrollContainer's size if it's larger (scroll is invisible for the chosen dimension). +A container used to provide a child control with scrollbars when needed. Scrollbars will automatically be drawn at the right (for vertical) or bottom (for horizontal) and will enable dragging to move the viewable Control (and its children) within the ScrollContainer. Scrollbars will also automatically resize the grabber based on the :ref:`Control.custom_minimum_size` of the Control relative to the ScrollContainer. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_semaphore.rst b/classes/class_semaphore.rst index 9f8c7e29e..5e77660e4 100644 --- a/classes/class_semaphore.rst +++ b/classes/class_semaphore.rst @@ -12,7 +12,7 @@ Semaphore **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A synchronization semaphore. +A synchronization mechanism used to control access to a shared resource by :ref:`Thread`\ s. .. rst-class:: classref-introduction-group @@ -28,6 +28,8 @@ Tutorials - :doc:`Using multiple threads <../tutorials/performance/using_multiple_threads>` +- :doc:`Thread-safe APIs <../tutorials/performance/thread_safe_apis>` + .. rst-class:: classref-reftable-group Methods diff --git a/classes/class_separator.rst b/classes/class_separator.rst index 8dc02e93e..90b7b03e5 100644 --- a/classes/class_separator.rst +++ b/classes/class_separator.rst @@ -14,14 +14,14 @@ Separator **Inherited By:** :ref:`HSeparator`, :ref:`VSeparator` -Base class for separators. +Abstract base class for separators. .. rst-class:: classref-introduction-group Description ----------- -Separator is a :ref:`Control` used for separating other controls. It's purely a visual decoration. Horizontal (:ref:`HSeparator`) and Vertical (:ref:`VSeparator`) versions are available. +Abstract base class for separators, used for separating other controls. **Separator**\ s are purely visual and normally drawn as a :ref:`StyleBoxLine`. .. |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_shaderinclude.rst b/classes/class_shaderinclude.rst index 833869fb7..8917d56d2 100644 --- a/classes/class_shaderinclude.rst +++ b/classes/class_shaderinclude.rst @@ -12,9 +12,21 @@ ShaderInclude **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -.. container:: contribute +A snippet of shader code to be included in a :ref:`Shader` with ``#include``. - There is currently no description for this class. Please help us by :ref:`contributing one `! +.. rst-class:: classref-introduction-group + +Description +----------- + +A shader include file, saved with the ``.gdshaderinc`` extension. This class allows you to define a custom shader snippet that can be included in a :ref:`Shader` by using the preprocessor directive ``#include``, followed by the file path (e.g. ``#include "res://shader_lib.gdshaderinc"``). The snippet doesn't have to be a valid shader on its own. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Shader preprocessor <../tutorials/shaders/shader_reference/shader_preprocessor>` .. rst-class:: classref-reftable-group @@ -48,9 +60,7 @@ Property Descriptions - void **set_code** **(** :ref:`String` value **)** - :ref:`String` **get_code** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Returns the code of the shader include file. The returned text is what the user has written, not the full generated code used internally. .. |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_signal.rst b/classes/class_signal.rst index d9542c22f..9626454e9 100644 --- a/classes/class_signal.rst +++ b/classes/class_signal.rst @@ -10,7 +10,7 @@ Signal ====== -Built-in type representing a signal defined in an object. +A built-in type representing a signal of an :ref:`Object`. .. rst-class:: classref-introduction-group diff --git a/classes/class_skeleton2d.rst b/classes/class_skeleton2d.rst index b7c087af5..295e11fab 100644 --- a/classes/class_skeleton2d.rst +++ b/classes/class_skeleton2d.rst @@ -12,16 +12,16 @@ Skeleton2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Skeleton for 2D characters and animated objects. +The parent of a hierarchy of :ref:`Bone2D`\ s, used to create a 2D skeletal animation. .. rst-class:: classref-introduction-group Description ----------- -Skeleton2D parents a hierarchy of :ref:`Bone2D` objects. It is a requirement of :ref:`Bone2D`. Skeleton2D holds a reference to the rest pose of its children and acts as a single point of access to its bones. +**Skeleton2D** parents a hierarchy of :ref:`Bone2D` nodes. It holds a reference to each :ref:`Bone2D`'s rest pose and acts as a single point of access to its bones. -To setup different types of inverse kinematics for the given Skeleton2D, a :ref:`SkeletonModificationStack2D` should be created. They can be applied by creating the desired number of modifications, which can be done by increasing :ref:`SkeletonModificationStack2D.modification_count`. +To set up different types of inverse kinematics for the given Skeleton2D, a :ref:`SkeletonModificationStack2D` should be created. The inverse kinematics be applied by increasing :ref:`SkeletonModificationStack2D.modification_count` and creating the desired number of modifications. .. rst-class:: classref-introduction-group diff --git a/classes/class_skeleton3d.rst b/classes/class_skeleton3d.rst index d5faba50c..1198e00b2 100644 --- a/classes/class_skeleton3d.rst +++ b/classes/class_skeleton3d.rst @@ -12,18 +12,18 @@ Skeleton3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Skeleton for characters and animated objects. +A node containing a bone hierarchy, used to create a 3D skeletal animation. .. rst-class:: classref-introduction-group Description ----------- -Skeleton3D provides a hierarchical interface for managing bones, including pose, rest and animation (see :ref:`Animation`). It can also use ragdoll physics. +**Skeleton3D** provides an interface for managing a hierarchy of bones, including pose, rest and animation (see :ref:`Animation`). It can also use ragdoll physics. -The overall transform of a bone with respect to the skeleton is determined by the following hierarchical order: rest pose, custom pose and pose. +The overall transform of a bone with respect to the skeleton is determined by bone pose. Bone rest defines the initial transform of the bone pose. -Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it not the actual global/world transform of the bone. +Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it is not the actual global/world transform of the bone. To setup different types of inverse kinematics, consider using :ref:`SkeletonIK3D`, or add a custom IK implementation in :ref:`Node._process` as a child node. @@ -479,7 +479,7 @@ Returns the bone index which is the parent of the bone at ``bone_idx``. If -1, t :ref:`Transform3D` **get_bone_pose** **(** :ref:`int` bone_idx **)** |const| -Returns the pose transform of the specified bone. Pose is applied on top of the custom pose, which is applied on top the rest pose. +Returns the pose transform of the specified bone. .. rst-class:: classref-item-separator diff --git a/classes/class_skeletonik3d.rst b/classes/class_skeletonik3d.rst index f1a005344..31159a225 100644 --- a/classes/class_skeletonik3d.rst +++ b/classes/class_skeletonik3d.rst @@ -12,14 +12,14 @@ SkeletonIK3D **Inherits:** :ref:`Node` **<** :ref:`Object` -SkeletonIK3D is used to place the end bone of a :ref:`Skeleton3D` bone chain at a certain point in 3D by rotating all bones in the chain accordingly. +A node used to rotate all bones of a :ref:`Skeleton3D` bone chain a way that places the end bone at a desired 3D position. .. rst-class:: classref-introduction-group Description ----------- -SkeletonIK3D is used to place the end bone of a :ref:`Skeleton3D` bone chain at a certain point in 3D by rotating all bones in the chain accordingly. A typical scenario for IK in games is to place a characters feet on the ground or a characters hands on a currently hold object. SkeletonIK uses FabrikInverseKinematic internally to solve the bone chain and applies the results to the :ref:`Skeleton3D` ``bones_global_pose_override`` property for all affected bones in the chain. If fully applied this overwrites any bone transform from :ref:`Animation`\ s or bone custom poses set by users. The applied amount can be controlled with the ``interpolation`` property. +SkeletonIK3D is used to rotate all bones of a :ref:`Skeleton3D` bone chain a way that places the end bone at a desired 3D position. A typical scenario for IK in games is to place a character's feet on the ground or a character's hands on a currently held object. SkeletonIK uses FabrikInverseKinematic internally to solve the bone chain and applies the results to the :ref:`Skeleton3D` ``bones_global_pose_override`` property for all affected bones in the chain. If fully applied, this overwrites any bone transform from :ref:`Animation`\ s or bone custom poses set by users. The applied amount can be controlled with the :ref:`interpolation` property. :: diff --git a/classes/class_skeletonmodification2d.rst b/classes/class_skeletonmodification2d.rst index a1689a533..e433be602 100644 --- a/classes/class_skeletonmodification2d.rst +++ b/classes/class_skeletonmodification2d.rst @@ -14,7 +14,7 @@ SkeletonModification2D **Inherited By:** :ref:`SkeletonModification2DCCDIK`, :ref:`SkeletonModification2DFABRIK`, :ref:`SkeletonModification2DJiggle`, :ref:`SkeletonModification2DLookAt`, :ref:`SkeletonModification2DPhysicalBones`, :ref:`SkeletonModification2DStackHolder`, :ref:`SkeletonModification2DTwoBoneIK` -A resource that operates on :ref:`Bone2D` nodes in a :ref:`Skeleton2D`. +Base class for resources that operate on :ref:`Bone2D`\ s in a :ref:`Skeleton2D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_skeletonmodification2dtwoboneik.rst b/classes/class_skeletonmodification2dtwoboneik.rst index 5b0dfb0ce..9d6f84e39 100644 --- a/classes/class_skeletonmodification2dtwoboneik.rst +++ b/classes/class_skeletonmodification2dtwoboneik.rst @@ -12,14 +12,14 @@ SkeletonModification2DTwoBoneIK **Inherits:** :ref:`SkeletonModification2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A modification that rotates two bones using the law of cosigns to reach the target. +A modification that rotates two bones using the law of cosines to reach the target. .. rst-class:: classref-introduction-group Description ----------- -This :ref:`SkeletonModification2D` uses an algorithm typically called TwoBoneIK. This algorithm works by leveraging the law of cosigns and the lengths of the bones to figure out what rotation the bones currently have, and what rotation they need to make a complete triangle, where the first bone, the second bone, and the target form the three vertices of the triangle. Because the algorithm works by making a triangle, it can only operate on two bones. +This :ref:`SkeletonModification2D` uses an algorithm typically called TwoBoneIK. This algorithm works by leveraging the law of cosines and the lengths of the bones to figure out what rotation the bones currently have, and what rotation they need to make a complete triangle, where the first bone, the second bone, and the target form the three vertices of the triangle. Because the algorithm works by making a triangle, it can only operate on two bones. TwoBoneIK is great for arms, legs, and really any joints that can be represented by just two bones that bend to reach a target. This solver is more lightweight than :ref:`SkeletonModification2DFABRIK`, but gives similar, natural looking results. diff --git a/classes/class_skeletonprofile.rst b/classes/class_skeletonprofile.rst index 23f6f73af..901b36d1f 100644 --- a/classes/class_skeletonprofile.rst +++ b/classes/class_skeletonprofile.rst @@ -14,7 +14,7 @@ SkeletonProfile **Inherited By:** :ref:`SkeletonProfileHumanoid` -Profile of a virtual skeleton used as a target for retargeting. +Base class for a profile of a virtual skeleton used as a target for retargeting. .. rst-class:: classref-introduction-group diff --git a/classes/class_slider.rst b/classes/class_slider.rst index 2580c9a9f..504cc55cc 100644 --- a/classes/class_slider.rst +++ b/classes/class_slider.rst @@ -14,16 +14,14 @@ Slider **Inherited By:** :ref:`HSlider`, :ref:`VSlider` -Base class for GUI sliders. +Abstract base class for sliders. .. rst-class:: classref-introduction-group Description ----------- -Base class for GUI sliders. - -\ **Note:** The :ref:`Range.changed` and :ref:`Range.value_changed` signals are part of the :ref:`Range` class which this class inherits from. +Abstract base class for sliders, used to adjust a value by moving a grabber along a horizontal or vertical axis. Sliders are :ref:`Range`-based controls. .. rst-class:: classref-reftable-group diff --git a/classes/class_spinbox.rst b/classes/class_spinbox.rst index 706fc5d95..f238346c6 100644 --- a/classes/class_spinbox.rst +++ b/classes/class_spinbox.rst @@ -12,14 +12,14 @@ SpinBox **Inherits:** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Numerical input text field. +An input field for numbers. .. rst-class:: classref-introduction-group Description ----------- -SpinBox is a numerical input text field. It allows entering integers and floats. +**SpinBox** is a numerical input text field. It allows entering integers and floating point numbers. \ **Example:**\ diff --git a/classes/class_splitcontainer.rst b/classes/class_splitcontainer.rst index ef9c97d6a..0ca19a582 100644 --- a/classes/class_splitcontainer.rst +++ b/classes/class_splitcontainer.rst @@ -14,21 +14,21 @@ SplitContainer **Inherited By:** :ref:`HSplitContainer`, :ref:`VSplitContainer` -Container for splitting and adjusting. +A container that splits two child controls horizontally or vertically and provides a grabber for adjusting the split ratio. .. rst-class:: classref-introduction-group Description ----------- -Container for splitting two :ref:`Control`\ s vertically or horizontally, with a grabber that allows adjusting the split offset or ratio. +A container that accepts only two child controls, then arranges them horizontally or vertically and creates a divisor between them. The divisor can be dragged around to change the size relation between the child controls. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_streampeer.rst b/classes/class_streampeer.rst index 20e487c52..e0ff55c49 100644 --- a/classes/class_streampeer.rst +++ b/classes/class_streampeer.rst @@ -14,14 +14,14 @@ StreamPeer **Inherited By:** :ref:`StreamPeerBuffer`, :ref:`StreamPeerExtension`, :ref:`StreamPeerGZIP`, :ref:`StreamPeerTCP`, :ref:`StreamPeerTLS` -Abstraction and base class for stream-based protocols. +Abstract base class for interacting with streams. .. rst-class:: classref-introduction-group Description ----------- -StreamPeer is an abstraction and base class for stream-based protocols (such as TCP). It provides an API for sending and receiving data through streams as raw data or strings. +StreamPeer is an abstract base class mostly used for stream-based protocols (such as TCP). It provides an API for sending and receiving data through streams as raw data or strings. \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. @@ -314,7 +314,7 @@ Gets an unsigned byte from the stream. :ref:`String` **get_utf8_string** **(** :ref:`int` bytes=-1 **)** -Gets an UTF-8 string with byte-length ``bytes`` from the stream (this decodes the string sent as UTF-8). If ``bytes`` is negative (default) the length will be read from the stream using the reverse process of :ref:`put_utf8_string`. +Gets a UTF-8 string with byte-length ``bytes`` from the stream (this decodes the string sent as UTF-8). If ``bytes`` is negative (default) the length will be read from the stream using the reverse process of :ref:`put_utf8_string`. .. rst-class:: classref-item-separator @@ -515,7 +515,7 @@ void **put_utf8_string** **(** :ref:`String` value **)** Puts a zero-terminated UTF-8 string into the stream prepended by a 32 bits unsigned integer representing its size. -\ **Note:** To put an UTF-8 string without prepending its size, you can use :ref:`put_data`: +\ **Note:** To put a UTF-8 string without prepending its size, you can use :ref:`put_data`: .. tabs:: diff --git a/classes/class_streampeerbuffer.rst b/classes/class_streampeerbuffer.rst index 593c7e5e7..0b0d3ae41 100644 --- a/classes/class_streampeerbuffer.rst +++ b/classes/class_streampeerbuffer.rst @@ -12,14 +12,14 @@ StreamPeerBuffer **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -Data buffer stream peer. +A stream peer used to handle binary data streams. .. rst-class:: classref-introduction-group Description ----------- -Data buffer stream peer that uses a byte array as the stream. This object can be used to handle binary data from network sessions. To handle binary data stored in files, :ref:`FileAccess` can be used directly. +A data buffer stream peer that uses a byte array as the stream. This object can be used to handle binary data from network sessions. To handle binary data stored in files, :ref:`FileAccess` can be used directly. A **StreamPeerBuffer** object keeps an internal cursor which is the offset in bytes to the start of the buffer. Get and put operations are performed at the cursor position and will move the cursor accordingly. diff --git a/classes/class_streampeergzip.rst b/classes/class_streampeergzip.rst index 2643e32b3..cd9abff26 100644 --- a/classes/class_streampeergzip.rst +++ b/classes/class_streampeergzip.rst @@ -12,14 +12,14 @@ StreamPeerGZIP **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -Stream peer handling GZIP and deflate compression/decompresison. +A stream peer that handles GZIP and deflate compression/decompression. .. rst-class:: classref-introduction-group Description ----------- -This class allows to compress or decompress data using GZIP/deflate in a streaming fashion. This is particularly useful when compressing or decompressing files that has to be sent through the network without having to allocate them all in memory. +This class allows to compress or decompress data using GZIP/deflate in a streaming fashion. This is particularly useful when compressing or decompressing files that have to be sent through the network without needing to allocate them all in memory. After starting the stream via :ref:`start_compression` (or :ref:`start_decompression`), calling :ref:`StreamPeer.put_partial_data` on this stream will compress (or decompress) the data, writing it to the internal buffer. Calling :ref:`StreamPeer.get_available_bytes` will return the pending bytes in the internal buffer, and :ref:`StreamPeer.get_partial_data` will retrieve the compressed (or decompressed) bytes from it. When the stream is over, you must call :ref:`finish` to ensure the internal buffer is properly flushed (make sure to call :ref:`StreamPeer.get_available_bytes` on last time to check if more data needs to be read after that). diff --git a/classes/class_streampeertcp.rst b/classes/class_streampeertcp.rst index 595587bcf..30accceb9 100644 --- a/classes/class_streampeertcp.rst +++ b/classes/class_streampeertcp.rst @@ -12,14 +12,14 @@ StreamPeerTCP **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -TCP stream peer. +A stream peer that handles TCP connections. .. rst-class:: classref-introduction-group Description ----------- -TCP stream peer. This object can be used to connect to TCP servers, or also is returned by a TCP server. +A stream peer that handles TCP connections. This object can be used to connect to TCP servers, or also is returned by a TCP server. \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. diff --git a/classes/class_streampeertls.rst b/classes/class_streampeertls.rst index 51b9f1a46..ef3450dca 100644 --- a/classes/class_streampeertls.rst +++ b/classes/class_streampeertls.rst @@ -12,14 +12,14 @@ StreamPeerTLS **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -TLS stream peer. +A stream peer that handles TLS connections. .. rst-class:: classref-introduction-group Description ----------- -TLS stream peer. This object can be used to connect to a TLS server or accept a single TLS client connection. +A stream peer that handles TLS connections. This object can be used to connect to a TLS server or accept a single TLS client connection. \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. diff --git a/classes/class_string.rst b/classes/class_string.rst index 62b54c2ed..c6d94e1aa 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -10,7 +10,7 @@ String ====== -Built-in string Variant type. +A built-in type for strings. .. rst-class:: classref-introduction-group @@ -1713,11 +1713,11 @@ Converts the string representing a decimal number into a :ref:`float`\ s, because only the pointers are compared, not the whole strings. +**StringName**\ s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). Two **StringName**\ s with the same value are the same object. Comparing them is extremely fast compared to regular :ref:`String`\ s. You will usually just pass a :ref:`String` to methods expecting a **StringName** and it will be automatically converted, but you may occasionally want to construct a **StringName** ahead of time with the **StringName** constructor or, in GDScript, the literal syntax ``&"example"``. -See also :ref:`NodePath`, which is a similar concept specifically designed to store pre-parsed node paths. +See also :ref:`NodePath`, which is a similar concept specifically designed to store pre-parsed scene tree paths. -Some string methods have corresponding variations. Variations suffixed with ``n`` (:ref:`countn`, :ref:`findn`, :ref:`replacen`, etc.) are **case-insensitive** (they make no distinction between uppercase and lowercase letters). Method variations prefixed with ``r`` (:ref:`rfind`, :ref:`rsplit`, etc.) are reversed, and start from the end of the string, instead of the beginning. +All of :ref:`String`'s methods are available in this class too. They convert the **StringName** into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired. \ **Note:** In a boolean context, a **StringName** will evaluate to ``false`` if it is empty (``StringName("")``). Otherwise, a **StringName** will always evaluate to ``true``. @@ -1886,7 +1886,7 @@ Appends ``right`` at the end of this **StringName**, returning a :ref:`String` **operator <** **(** :ref:`StringName` right **)** -Returns ``true`` if the left :ref:`String` comes before ``right`` in `Unicode order `__, which roughly matches the alphabetical order. Useful for sorting. +Returns ``true`` if the left **StringName**'s pointer comes before ``right``. Note that this will not match their `Unicode order `__. .. rst-class:: classref-item-separator @@ -1898,7 +1898,7 @@ Returns ``true`` if the left :ref:`String` comes before ``right`` :ref:`bool` **operator <=** **(** :ref:`StringName` right **)** -Returns ``true`` if the left :ref:`String` comes before ``right`` in `Unicode order `__, which roughly matches the alphabetical order, or if both are equal. +Returns ``true`` if the left **StringName**'s pointer comes before ``right`` or if they are the same. Note that this will not match their `Unicode order `__. .. rst-class:: classref-item-separator @@ -1934,7 +1934,7 @@ Returns ``true`` if the **StringName** and ``right`` refer to the same name. Com :ref:`bool` **operator >** **(** :ref:`StringName` right **)** -Returns ``true`` if the left **StringName** comes after ``right`` in `Unicode order `__, which roughly matches the alphabetical order. Useful for sorting. +Returns ``true`` if the left **StringName**'s pointer comes after ``right``. Note that this will not match their `Unicode order `__. .. rst-class:: classref-item-separator @@ -1946,7 +1946,7 @@ Returns ``true`` if the left **StringName** comes after ``right`` in `Unicode or :ref:`bool` **operator >=** **(** :ref:`StringName` right **)** -Returns ``true`` if the left **StringName** comes after ``right`` in `Unicode order `__, which roughly matches the alphabetical order, or if both are equal. +Returns ``true`` if the left **StringName**'s pointer comes after ``right`` or if they are the same. Note that this will not match their `Unicode order `__. .. |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_stylebox.rst b/classes/class_stylebox.rst index 8ef209ac6..fb5be5cff 100644 --- a/classes/class_stylebox.rst +++ b/classes/class_stylebox.rst @@ -14,16 +14,16 @@ StyleBox **Inherited By:** :ref:`StyleBoxEmpty`, :ref:`StyleBoxFlat`, :ref:`StyleBoxLine`, :ref:`StyleBoxTexture` -Base class for drawing stylized boxes for the UI. +Abstract base class for defining stylized boxes for UI elements. .. rst-class:: classref-introduction-group Description ----------- -StyleBox is :ref:`Resource` that provides an abstract base class for drawing stylized boxes for the UI. StyleBoxes are used for drawing the styles of buttons, line edit backgrounds, tree backgrounds, etc. and also for testing a transparency mask for pointer signals. If mask test fails on a StyleBox assigned as mask to a control, clicks and motion signals will go through it to the one below. +**StyleBox** is an abstract base class for drawing stylized boxes for UI elements. It is used for panels, buttons, :ref:`LineEdit` backgrounds, :ref:`Tree` backgrounds, etc. and also for testing a transparency mask for pointer signals. If mask test fails on a **StyleBox** assigned as mask to a control, clicks and motion signals will go through it to the one below. -\ **Note:** For children of :ref:`Control` that have *Theme Properties*, the ``focus`` **StyleBox** is displayed over the ``normal``, ``hover`` or ``pressed`` **StyleBox**. This makes the ``focus`` **StyleBox** more reusable across different nodes. +\ **Note:** For control nodes that have *Theme Properties*, the ``focus`` **StyleBox** is displayed over the ``normal``, ``hover`` or ``pressed`` **StyleBox**. This makes the ``focus`` **StyleBox** more reusable across different nodes. .. rst-class:: classref-reftable-group diff --git a/classes/class_styleboxempty.rst b/classes/class_styleboxempty.rst index 8951c9ca0..5b581798d 100644 --- a/classes/class_styleboxempty.rst +++ b/classes/class_styleboxempty.rst @@ -12,14 +12,14 @@ StyleBoxEmpty **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Empty stylebox (does not display anything). +An empty :ref:`StyleBox` (does not display anything). .. rst-class:: classref-introduction-group Description ----------- -Empty stylebox (really does not display anything). +An empty :ref:`StyleBox` that can be used to display nothing instead of the default style (e.g. it can "disable" ``focus`` styles). .. |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_styleboxflat.rst b/classes/class_styleboxflat.rst index caad00fb9..e188e3f8c 100644 --- a/classes/class_styleboxflat.rst +++ b/classes/class_styleboxflat.rst @@ -12,22 +12,14 @@ StyleBoxFlat **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Customizable :ref:`StyleBox` with a given set of parameters (no texture required). +A customizable :ref:`StyleBox` that doesn't use a texture. .. rst-class:: classref-introduction-group Description ----------- -This :ref:`StyleBox` can be used to achieve all kinds of looks without the need of a texture. The following properties are customizable: - -- Color - -- Border width (individual width for each border) - -- Rounded corners (individual radius for each corner) - -- Shadow (with blur and offset) +By configuring various properties of this style box, you can achieve many common looks without the need of a texture. This includes optionally rounded borders, antialiasing, shadows, and skew. Setting corner radius to high values is allowed. As soon as corners overlap, the stylebox will switch to a relative system. diff --git a/classes/class_styleboxline.rst b/classes/class_styleboxline.rst index fe122efd3..79c404580 100644 --- a/classes/class_styleboxline.rst +++ b/classes/class_styleboxline.rst @@ -12,14 +12,14 @@ StyleBoxLine **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`StyleBox` that displays a single line. +A :ref:`StyleBox` that displays a single line of a given color and thickness. .. rst-class:: classref-introduction-group Description ----------- -:ref:`StyleBox` that displays a single line of a given color and thickness. It can be used to draw things like separators. +A :ref:`StyleBox` that displays a single line of a given color and thickness. The line can be either horizontal or vertical. Useful for separators. .. rst-class:: classref-reftable-group diff --git a/classes/class_styleboxtexture.rst b/classes/class_styleboxtexture.rst index a7f7c2367..d4c0ed357 100644 --- a/classes/class_styleboxtexture.rst +++ b/classes/class_styleboxtexture.rst @@ -12,14 +12,14 @@ StyleBoxTexture **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Texture-based nine-patch :ref:`StyleBox`. +A texture-based nine-patch :ref:`StyleBox`. .. rst-class:: classref-introduction-group Description ----------- -Texture-based nine-patch :ref:`StyleBox`, in a way similar to :ref:`NinePatchRect`. This stylebox performs a 3×3 scaling of a texture, where only the center cell is fully stretched. This makes it possible to design bordered styles regardless of the stylebox's size. +A texture-based nine-patch :ref:`StyleBox`, in a way similar to :ref:`NinePatchRect`. This stylebox performs a 3×3 scaling of a texture, where only the center cell is fully stretched. This makes it possible to design bordered styles regardless of the stylebox's size. .. rst-class:: classref-reftable-group diff --git a/classes/class_subviewport.rst b/classes/class_subviewport.rst index 9fd41b4d9..3065eb529 100644 --- a/classes/class_subviewport.rst +++ b/classes/class_subviewport.rst @@ -12,14 +12,16 @@ SubViewport **Inherits:** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -Creates a sub-view into the screen. +An interface to a game world that doesn't create a window or draw to the screen directly. .. rst-class:: classref-introduction-group Description ----------- -**SubViewport** is a :ref:`Viewport` that isn't a :ref:`Window`, i.e. it doesn't draw anything by itself. To display something, **SubViewport**'s :ref:`size` must be non-zero and it should be either put inside a :ref:`SubViewportContainer` or assigned to a :ref:`ViewportTexture`. +**SubViewport** Isolates a rectangular region of a scene to be displayed independently. This can be used, for example, to display UI in 3D space. + +\ **Note:** **SubViewport** is a :ref:`Viewport` that isn't a :ref:`Window`, i.e. it doesn't draw anything by itself. To display anything, **SubViewport** must have a non-zero size and be either put inside a :ref:`SubViewportContainer` or assigned to a :ref:`ViewportTexture`. .. rst-class:: classref-introduction-group diff --git a/classes/class_subviewportcontainer.rst b/classes/class_subviewportcontainer.rst index da55db8d2..34a7def79 100644 --- a/classes/class_subviewportcontainer.rst +++ b/classes/class_subviewportcontainer.rst @@ -12,18 +12,18 @@ SubViewportContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control for holding :ref:`SubViewport`\ s. +A container used for displaying the contents of a :ref:`SubViewport`. .. rst-class:: classref-introduction-group Description ----------- -A :ref:`Container` node that holds a :ref:`SubViewport`. It uses the :ref:`SubViewport`'s size as minimum size, unless :ref:`stretch` is enabled. +A container that displays the contents of underlying :ref:`SubViewport` child nodes. It uses the combined size of the :ref:`SubViewport`\ s as minimum size, unless :ref:`stretch` is enabled. -\ **Note:** Changing a SubViewportContainer's :ref:`Control.scale` will cause its contents to appear distorted. To change its visual size without causing distortion, adjust the node's margins instead (if it's not already in a container). +\ **Note:** Changing a **SubViewportContainer**'s :ref:`Control.scale` will cause its contents to appear distorted. To change its visual size without causing distortion, adjust the node's margins instead (if it's not already in a container). -\ **Note:** The SubViewportContainer forwards mouse-enter and mouse-exit notifications to its sub-viewports. +\ **Note:** The **SubViewportContainer** forwards mouse-enter and mouse-exit notifications to its sub-viewports. .. rst-class:: classref-reftable-group diff --git a/classes/class_surfacetool.rst b/classes/class_surfacetool.rst index f12df05a9..facb8c6f3 100644 --- a/classes/class_surfacetool.rst +++ b/classes/class_surfacetool.rst @@ -37,7 +37,7 @@ The **SurfaceTool** is used to construct a :ref:`Mesh` by specifying var st = new SurfaceTool(); st.Begin(Mesh.PrimitiveType.Triangles); st.SetColor(new Color(1, 0, 0)); - st.SetUv(new Vector2(0, 0)); + st.SetUV(new Vector2(0, 0)); st.AddVertex(new Vector3(0, 0, 0)); @@ -611,7 +611,7 @@ void **set_smooth_group** **(** :ref:`int` index **)** Specifies the smooth group to use for the *next* vertex. If this is never called, all vertices will have the default smooth group of ``0`` and will be smoothed with adjacent vertices of the same group. To produce a mesh with flat normals, set the smooth group to ``-1``. -\ **Note:** This function actually takes an ``uint32_t``, so C# users should use ``uint32.MaxValue`` instead of ``-1`` to produce a mesh with flat normals. +\ **Note:** This function actually takes a ``uint32_t``, so C# users should use ``uint32.MaxValue`` instead of ``-1`` to produce a mesh with flat normals. .. rst-class:: classref-item-separator diff --git a/classes/class_syntaxhighlighter.rst b/classes/class_syntaxhighlighter.rst index 36cacdb8c..0fdff03fb 100644 --- a/classes/class_syntaxhighlighter.rst +++ b/classes/class_syntaxhighlighter.rst @@ -14,18 +14,16 @@ SyntaxHighlighter **Inherited By:** :ref:`CodeHighlighter`, :ref:`EditorSyntaxHighlighter` -Base Syntax highlighter resource for :ref:`TextEdit`. +Base class for syntax highlighters. Provides syntax highlighting data to a :ref:`TextEdit`. .. rst-class:: classref-introduction-group Description ----------- -Base syntax highlighter resource all syntax highlighters extend from, provides syntax highlighting data to :ref:`TextEdit`. +Base class for syntax highlighters. Provides syntax highlighting data to a :ref:`TextEdit`. The associated :ref:`TextEdit` will call into the **SyntaxHighlighter** on an as-needed basis. -The associated :ref:`TextEdit` node will call into the **SyntaxHighlighter** on an as-needed basis. - -\ **Note:** Each Syntax highlighter instance should not be shared across multiple :ref:`TextEdit` nodes. +\ **Note:** A **SyntaxHighlighter** instance should not be used across multiple :ref:`TextEdit` nodes. .. rst-class:: classref-reftable-group diff --git a/classes/class_systemfont.rst b/classes/class_systemfont.rst index 289ccde62..10c13ce99 100644 --- a/classes/class_systemfont.rst +++ b/classes/class_systemfont.rst @@ -12,9 +12,7 @@ SystemFont **Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Font loaded from a system font. - -\ **Note:** This class is implemented on iOS, Linux, macOS and Windows, on other platforms it will fallback to default theme font. +A font loaded from a system font. Falls back to a default theme font if not implemented on the host OS. .. rst-class:: classref-introduction-group @@ -29,6 +27,8 @@ The returned font might be part of a font collection or be a variable font with You can create :ref:`FontVariation` of the system font for fine control over its features. +\ **Note:** This class is implemented on iOS, Linux, macOS and Windows, on other platforms it will fallback to default theme font. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_tabbar.rst b/classes/class_tabbar.rst index 5c7fc09dd..73dbf6bd0 100644 --- a/classes/class_tabbar.rst +++ b/classes/class_tabbar.rst @@ -12,14 +12,14 @@ TabBar **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tab bar control. +A control that provides a horizontal bar with tabs. .. rst-class:: classref-introduction-group Description ----------- -Simple tabs control, similar to :ref:`TabContainer` but is only in charge of drawing tabs, not interacting with children. +A control that provides a horizontal bar with tabs. Similar to :ref:`TabContainer` but is only in charge of drawing tabs, not interacting with children. .. rst-class:: classref-reftable-group diff --git a/classes/class_tabcontainer.rst b/classes/class_tabcontainer.rst index 59383f78a..c789c6761 100644 --- a/classes/class_tabcontainer.rst +++ b/classes/class_tabcontainer.rst @@ -12,25 +12,23 @@ TabContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tabbed container. +A container that creates a tab for each child control, displaying only the active tab's control. .. rst-class:: classref-introduction-group Description ----------- -Arranges :ref:`Control` children into a tabbed view, creating a tab for each one. The active tab's corresponding :ref:`Control` has its ``visible`` property set to ``true``, and all other children's to ``false``. +Arranges child controls into a tabbed view, creating a tab for each one. The active tab's corresponding control is made visible, while all other child controls are hidden. Ignores non-control children. -Ignores non-:ref:`Control` children. - -\ **Note:** The drawing of the clickable tabs themselves is handled by this node. Adding :ref:`TabBar`\ s as children is not needed. +\ **Note:** The drawing of the clickable tabs is handled by this node; :ref:`TabBar` is not needed. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_textedit.rst b/classes/class_textedit.rst index b6ef86326..dfa872cd7 100644 --- a/classes/class_textedit.rst +++ b/classes/class_textedit.rst @@ -14,14 +14,14 @@ TextEdit **Inherited By:** :ref:`CodeEdit` -Multiline text editing control. +A multiline text editor. .. rst-class:: classref-introduction-group Description ----------- -TextEdit is meant for editing large, multiline text. It also has facilities for editing code, such as syntax highlighting support and multiple levels of undo/redo. +A multiline text editor. It also has limited facilities for editing code, such as syntax highlighting support. For more advanced facilities for editing code, see :ref:`CodeEdit`. \ **Note:** Most viewport, caret and edit methods contain a ``caret_index`` argument for :ref:`caret_multiple` support. The argument should be one of the following: ``-1`` for all carets, ``0`` for the main caret, or greater than ``0`` for secondary carets. @@ -2222,7 +2222,9 @@ Returns the text currently in ``gutter`` at ``line``. :ref:`int` **get_line_height** **(** **)** |const| -Returns the height of a largest line. +Returns the maximum value of the line height among all lines. + +\ **Note:** The return value is influenced by :ref:`line_spacing` and :ref:`font_size`. And it will not be less than ``1``. .. rst-class:: classref-item-separator diff --git a/classes/class_textline.rst b/classes/class_textline.rst index a2123fed8..44dcc8902 100644 --- a/classes/class_textline.rst +++ b/classes/class_textline.rst @@ -19,7 +19,7 @@ Holds a line of text. Description ----------- -Abstraction over :ref:`TextServer` for handling single line of text. +Abstraction over :ref:`TextServer` for handling a single line of text. .. rst-class:: classref-reftable-group diff --git a/classes/class_textparagraph.rst b/classes/class_textparagraph.rst index ec9fc23df..8fffd8c53 100644 --- a/classes/class_textparagraph.rst +++ b/classes/class_textparagraph.rst @@ -19,7 +19,7 @@ Holds a paragraph of text. Description ----------- -Abstraction over :ref:`TextServer` for handling paragraph of text. +Abstraction over :ref:`TextServer` for handling a single paragraph of text. .. rst-class:: classref-reftable-group diff --git a/classes/class_textserver.rst b/classes/class_textserver.rst index eb47e900f..f80c56831 100644 --- a/classes/class_textserver.rst +++ b/classes/class_textserver.rst @@ -14,14 +14,14 @@ TextServer **Inherited By:** :ref:`TextServerExtension` -Interface for the fonts and complex text layouts. +A server interface for font management and text rendering. .. rst-class:: classref-introduction-group Description ----------- -**TextServer** is the API backend for managing fonts, and rendering complex text. +**TextServer** is the API backend for managing fonts and rendering text. .. rst-class:: classref-reftable-group @@ -1445,7 +1445,7 @@ Method Descriptions :ref:`RID` **create_font** **(** **)** -Creates new, empty font cache entry resource. To free the resulting resource, use :ref:`free_rid` method. +Creates a new, empty font cache entry resource. To free the resulting resource, use the :ref:`free_rid` method. .. rst-class:: classref-item-separator diff --git a/classes/class_textserveradvanced.rst b/classes/class_textserveradvanced.rst index 2202b83fd..bbb3b898a 100644 --- a/classes/class_textserveradvanced.rst +++ b/classes/class_textserveradvanced.rst @@ -12,7 +12,14 @@ TextServerAdvanced **Inherits:** :ref:`TextServerExtension` **<** :ref:`TextServer` **<** :ref:`RefCounted` **<** :ref:`Object` -Text Server using HarfBuzz, ICU and SIL Graphite to support BiDi, complex text layouts and contextual OpenType features. +An advanced text server with support for BiDi, complex text layout, and contextual OpenType features. Used in Godot by default. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An implementation of :ref:`TextServer` that uses HarfBuzz, ICU and SIL Graphite to support BiDi, complex text layouts and contextual OpenType features. This is Godot's default primary :ref:`TextServer` interface. .. |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_textserverextension.rst b/classes/class_textserverextension.rst index 7409b7360..66632ba6a 100644 --- a/classes/class_textserverextension.rst +++ b/classes/class_textserverextension.rst @@ -14,14 +14,14 @@ TextServerExtension **Inherited By:** :ref:`TextServerAdvanced`, :ref:`TextServerDummy`, :ref:`TextServerFallback` -Base class for TextServer custom implementations (plugins). +Base class for custom :ref:`TextServer` implementations (plugins). .. rst-class:: classref-introduction-group Description ----------- -External TextServer implementations should inherit from this class. +External :ref:`TextServer` implementations should inherit from this class. .. rst-class:: classref-reftable-group diff --git a/classes/class_textserverfallback.rst b/classes/class_textserverfallback.rst index 314485bff..552dcf926 100644 --- a/classes/class_textserverfallback.rst +++ b/classes/class_textserverfallback.rst @@ -12,7 +12,16 @@ TextServerFallback **Inherits:** :ref:`TextServerExtension` **<** :ref:`TextServer` **<** :ref:`RefCounted` **<** :ref:`Object` -Fallback implementation of the Text Server, without BiDi and complex text layout support. +A fallback implementation of Godot's text server, without support for BiDi and complex text layout. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A fallback implementation of Godot's text server. This fallback is faster than :ref:`TextServerAdvanced` for processing a lot of text, but it does not support BiDi and complex text layout. + +\ **Note:** This text server is not part of official Godot binaries. If you want to use it, compile the engine with the option ``module_text_server_fb_enabled=yes``. .. |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_textservermanager.rst b/classes/class_textservermanager.rst index 1be301a82..9f1c53e57 100644 --- a/classes/class_textservermanager.rst +++ b/classes/class_textservermanager.rst @@ -12,14 +12,14 @@ TextServerManager **Inherits:** :ref:`Object` -Manager for the font and complex text layout servers. +A singleton for managing :ref:`TextServer` implementations. .. rst-class:: classref-introduction-group Description ----------- -**TextServerManager** is the API backend for loading, enumeration and switching :ref:`TextServer`\ s. +**TextServerManager** is the API backend for loading, enumerating, and switching :ref:`TextServer`\ s. \ **Note:** Switching text server at runtime is possible, but will invalidate all fonts and text buffers. Make sure to unload all controls, fonts, and themes before doing so. @@ -93,7 +93,7 @@ Method Descriptions void **add_interface** **(** :ref:`TextServer` interface **)** -Registers an :ref:`TextServer` interface. +Registers a :ref:`TextServer` interface. .. rst-class:: classref-item-separator @@ -105,7 +105,7 @@ Registers an :ref:`TextServer` interface. :ref:`TextServer` **find_interface** **(** :ref:`String` name **)** |const| -Finds an interface by its name. +Finds an interface by its ``name``. .. rst-class:: classref-item-separator @@ -141,7 +141,7 @@ Returns the number of interfaces currently registered. :ref:`Dictionary[]` **get_interfaces** **(** **)** |const| -Returns a list of available interfaces the index and name of each interface. +Returns a list of available interfaces, with the index and name of each interface. .. rst-class:: classref-item-separator @@ -165,7 +165,7 @@ Returns the primary :ref:`TextServer` interface currently in u void **remove_interface** **(** :ref:`TextServer` interface **)** -Removes interface. All fonts and shaped text caches should be freed before removing interface. +Removes an interface. All fonts and shaped text caches should be freed before removing an interface. .. rst-class:: classref-item-separator diff --git a/classes/class_texturerect.rst b/classes/class_texturerect.rst index 622edc8b5..87fb945f5 100644 --- a/classes/class_texturerect.rst +++ b/classes/class_texturerect.rst @@ -12,14 +12,14 @@ TextureRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control for drawing textures. +A control that displays a texture. .. rst-class:: classref-introduction-group Description ----------- -Used to draw icons and sprites in a user interface. The texture's placement can be controlled with the :ref:`stretch_mode` property. It can scale, tile, or stay centered inside its bounding rectangle. +A control that displays a texture, for example an icon inside a GUI. The texture's placement can be controlled with the :ref:`stretch_mode` property. It can scale, tile, or stay centered inside its bounding rectangle. .. rst-class:: classref-introduction-group diff --git a/classes/class_theme.rst b/classes/class_theme.rst index 45c3bd989..ac4fb646f 100644 --- a/classes/class_theme.rst +++ b/classes/class_theme.rst @@ -12,14 +12,14 @@ Theme **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Theme resource for styling/skinning :ref:`Control`\ s and :ref:`Window`\ s. +A resource used for styling/skinning :ref:`Control`\ s and :ref:`Window`\ s. .. rst-class:: classref-introduction-group Description ----------- -A theme resource is used for styling/skinning :ref:`Control` and :ref:`Window` nodes. While individual controls can be styled using their local theme overrides (see :ref:`Control.add_theme_color_override`), theme resources allow you to store and apply the same settings between all controls sharing the same type (e.g. style all :ref:`Button`\ s the same). One theme resource can be used for the entire project, but you can also set a separate theme resource to a branch of control nodes. A theme resources assigned to a control node applies to the control itself, as well as all of its direct and indirect children (as long as a chain of controls is uninterrupted). +A resource used for styling/skinning :ref:`Control` and :ref:`Window` nodes. While individual controls can be styled using their local theme overrides (see :ref:`Control.add_theme_color_override`), theme resources allow you to store and apply the same settings across all controls sharing the same type (e.g. style all :ref:`Button`\ s the same). One theme resource can be used for the entire project, but you can also set a separate theme resource to a branch of control nodes. A theme resource assigned to a control applies to the control itself, as well as all of its direct and indirect children (as long as a chain of controls is uninterrupted). Use :ref:`ProjectSettings.gui/theme/custom` to set up a project-scope theme that will be available to every control in your project. diff --git a/classes/class_themedb.rst b/classes/class_themedb.rst index b8362f5d5..e42c4f9d1 100644 --- a/classes/class_themedb.rst +++ b/classes/class_themedb.rst @@ -12,14 +12,14 @@ ThemeDB **Inherits:** :ref:`Object` -An engine singleton providing access to static :ref:`Theme` information, such as default and project theme, and fallback values. +A singleton that provides access to static information about :ref:`Theme` resources used by the engine and by your project. .. rst-class:: classref-introduction-group Description ----------- -This engine singleton provides access to static information about :ref:`Theme` resources used by the engine and by your projects. You can fetch the default engine theme, as well as your project configured theme. +This singleton provides access to static information about :ref:`Theme` resources used by the engine and by your projects. You can fetch the default engine theme, as well as your project configured theme. \ **ThemeDB** also contains fallback values for theme properties. diff --git a/classes/class_thread.rst b/classes/class_thread.rst index 270daf8ad..f0895c512 100644 --- a/classes/class_thread.rst +++ b/classes/class_thread.rst @@ -170,8 +170,6 @@ Should either be used when you want to retrieve the value returned from the meth To determine if this can be called without blocking the calling thread, check if :ref:`is_alive` is ``false``. -\ **Note:** After the **Thread** finishes joining it will be disposed. If you want to use it again you will have to create a new instance of it. - .. |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_tilemap.rst b/classes/class_tilemap.rst index 328a2ffce..3f6e20234 100644 --- a/classes/class_tilemap.rst +++ b/classes/class_tilemap.rst @@ -251,7 +251,7 @@ The TileMap's quadrant size. Optimizes drawing by batching, using chunks of this If enabled, the TileMap will see its collisions synced to the physics tick and change its collision type from static to kinematic. This is required to create TileMap-based moving platform. -\ **Note:** Enabling ``collision_animatable`` may have a small performance impact, only do it if the TileMap is moving and has colliding tiles. +\ **Note:** Enabling :ref:`collision_animatable` may have a small performance impact, only do it if the TileMap is moving and has colliding tiles. .. rst-class:: classref-item-separator @@ -763,7 +763,7 @@ Update all the cells in the ``cells`` coordinates array so that they use the giv If ``ignore_empty_terrains`` is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. -\ **Note:** To work correctly, ``set_cells_terrain_connect`` requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. +\ **Note:** To work correctly, this method requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. .. rst-class:: classref-item-separator @@ -779,7 +779,7 @@ Update all the cells in the ``path`` coordinates array so that they use the give If ``ignore_empty_terrains`` is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. -\ **Note:** To work correctly, ``set_cells_terrain_path`` requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. +\ **Note:** To work correctly, this method requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. .. rst-class:: classref-item-separator diff --git a/classes/class_time.rst b/classes/class_time.rst index 8afb0789c..91ef0048f 100644 --- a/classes/class_time.rst +++ b/classes/class_time.rst @@ -12,7 +12,7 @@ Time **Inherits:** :ref:`Object` -Time singleton for working with time. +A singleton for working with time data. .. rst-class:: classref-introduction-group diff --git a/classes/class_tlsoptions.rst b/classes/class_tlsoptions.rst index 6cb0621aa..9b23cbdbe 100644 --- a/classes/class_tlsoptions.rst +++ b/classes/class_tlsoptions.rst @@ -35,7 +35,7 @@ Objects of this class cannot be instantiated directly, and one of the static met # Create a TLS server configuration. var server_certs = load("res://my_server_cas.crt") var server_key = load("res://my_server_key.key") - var server_tls_options = TLSOptions.server(server_certs, server_key) + var server_tls_options = TLSOptions.server(server_key, server_certs) diff --git a/classes/class_transform2d.rst b/classes/class_transform2d.rst index 59e6f1bf0..2761e0645 100644 --- a/classes/class_transform2d.rst +++ b/classes/class_transform2d.rst @@ -10,14 +10,14 @@ Transform2D =========== -2D transformation (2×3 matrix). +A 2×3 matrix representing a 2D transformation. .. rst-class:: classref-introduction-group Description ----------- -2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, or scaling. It consists of three :ref:`Vector2` values: :ref:`x`, :ref:`y`, and the :ref:`origin`. +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. diff --git a/classes/class_transform3d.rst b/classes/class_transform3d.rst index db342276c..0453fc686 100644 --- a/classes/class_transform3d.rst +++ b/classes/class_transform3d.rst @@ -10,14 +10,14 @@ Transform3D =========== -3D transformation (3×4 matrix). +A 3×4 matrix representing a 3D transformation. .. rst-class:: classref-introduction-group Description ----------- -3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, or scaling. It consists of a :ref:`basis` (first 3 columns) and a :ref:`Vector3` for the :ref:`origin` (last column). +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. diff --git a/classes/class_translation.rst b/classes/class_translation.rst index 0c1355a40..aa7eda59e 100644 --- a/classes/class_translation.rst +++ b/classes/class_translation.rst @@ -14,14 +14,14 @@ Translation **Inherited By:** :ref:`OptimizedTranslation` -Language Translation. +A language translation that maps a collection of strings to their individual translations. .. rst-class:: classref-introduction-group Description ----------- -Translations are resources that can be loaded and unloaded on demand. They map a string to another string. +**Translation**\ s are resources that can be loaded and unloaded on demand. They map a collection of strings to their individual translations, and they also provide convenience methods for pluralization. .. rst-class:: classref-introduction-group diff --git a/classes/class_translationserver.rst b/classes/class_translationserver.rst index 040aaafcd..a2191a625 100644 --- a/classes/class_translationserver.rst +++ b/classes/class_translationserver.rst @@ -12,14 +12,14 @@ TranslationServer **Inherits:** :ref:`Object` -Server that manages all translations. +The server responsible for language translations. .. rst-class:: classref-introduction-group Description ----------- -Server that manages all translations. Translations can be set to it and removed from it. +The server that manages all language translations. Translations can be added to or removed from it. .. rst-class:: classref-introduction-group @@ -155,7 +155,7 @@ Clears the server from all translations. :ref:`int` **compare_locales** **(** :ref:`String` locale_a, :ref:`String` locale_b **)** |const| -Compares two locales and return similarity score between ``0``\ (no match) and ``10``\ (full match). +Compares two locales and returns a similarity score between ``0`` (no match) and ``10`` (full match). .. rst-class:: classref-item-separator @@ -167,7 +167,7 @@ Compares two locales and return similarity score between ``0``\ (no match) and ` :ref:`PackedStringArray` **get_all_countries** **(** **)** |const| -Returns array of known country codes. +Returns an array of known country codes. .. rst-class:: classref-item-separator @@ -191,7 +191,7 @@ Returns array of known language codes. :ref:`PackedStringArray` **get_all_scripts** **(** **)** |const| -Returns array of known script codes. +Returns an array of known script codes. .. rst-class:: classref-item-separator @@ -203,7 +203,7 @@ Returns array of known script codes. :ref:`String` **get_country_name** **(** :ref:`String` country **)** |const| -Returns readable country name for the ``country`` code. +Returns a readable country name for the ``country`` code. .. rst-class:: classref-item-separator @@ -215,7 +215,7 @@ Returns readable country name for the ``country`` code. :ref:`String` **get_language_name** **(** :ref:`String` language **)** |const| -Returns readable language name for the ``language`` code. +Returns a readable language name for the ``language`` code. .. rst-class:: classref-item-separator @@ -265,7 +265,7 @@ Returns a locale's language and its variant (e.g. ``"en_US"`` would return ``"En :ref:`String` **get_script_name** **(** :ref:`String` script **)** |const| -Returns readable script name for the ``script`` code. +Returns a readable script name for the ``script`` code. .. rst-class:: classref-item-separator @@ -355,7 +355,7 @@ If translations have been loaded beforehand for the new locale, they will be app :ref:`String` **standardize_locale** **(** :ref:`String` locale **)** |const| -Returns ``locale`` string standardized to match known locales (e.g. ``en-US`` would be matched to ``en_US``). +Returns a ``locale`` string standardized to match known locales (e.g. ``en-US`` would be matched to ``en_US``). .. rst-class:: classref-item-separator diff --git a/classes/class_tree.rst b/classes/class_tree.rst index befe5d865..d46fe9104 100644 --- a/classes/class_tree.rst +++ b/classes/class_tree.rst @@ -12,16 +12,16 @@ Tree **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control to show a tree of items. +A control used to show a set of internal :ref:`TreeItem`\ s in a hierarchical structure. .. rst-class:: classref-introduction-group Description ----------- -This shows a tree of items that can be selected, expanded and collapsed. The tree can have multiple columns with custom controls like text editing, buttons and popups. It can be useful for structured displays and interactions. +A control used to show a set of internal :ref:`TreeItem`\ s in a hierarchical structure. The tree items can be selected, expanded and collapsed. The tree can have multiple columns with custom controls like :ref:`LineEdit`\ s, buttons and popups. It can be useful for structured displays and interactions. -Trees are built via code, using :ref:`TreeItem` objects to create the structure. They have a single root but multiple roots can be simulated if a dummy hidden root is added. +Trees are built via code, using :ref:`TreeItem` objects to create the structure. They have a single root, but multiple roots can be simulated with :ref:`hide_root`: .. tabs:: diff --git a/classes/class_treeitem.rst b/classes/class_treeitem.rst index 129c6935d..098ec6d8d 100644 --- a/classes/class_treeitem.rst +++ b/classes/class_treeitem.rst @@ -12,16 +12,18 @@ TreeItem **Inherits:** :ref:`Object` -Control for a single item inside a :ref:`Tree`. +An internal control for a single item inside :ref:`Tree`. .. rst-class:: classref-introduction-group Description ----------- -Control for a single item inside a :ref:`Tree`. May have child **TreeItem**\ s and be styled as well as contain buttons. +A single item of a :ref:`Tree` control. It can contain other **TreeItem**\ s as children, which allows it to create a hierarchy. It can also contain text and buttons. **TreeItem** is not a :ref:`Node`, it is internal to the :ref:`Tree`. -You can remove a **TreeItem** by using :ref:`Object.free`. +To create a **TreeItem**, use :ref:`Tree.create_item` or :ref:`create_child`. To remove a **TreeItem**, use :ref:`Object.free`. + +\ **Note:** The ID values used for buttons are 32-bit, unlike :ref:`int` which is always 64-bit. They go from ``-2147483648`` to ``2147483647``. .. rst-class:: classref-reftable-group diff --git a/classes/class_undoredo.rst b/classes/class_undoredo.rst index f3ea5ae50..fbe3a3049 100644 --- a/classes/class_undoredo.rst +++ b/classes/class_undoredo.rst @@ -12,18 +12,18 @@ UndoRedo **Inherits:** :ref:`Object` -General-purpose helper to manage undo/redo operations. +Provides a high-level interface for implementing undo and redo operations. .. rst-class:: classref-introduction-group Description ----------- -UndoRedo works by registering methods and property changes inside "actions". +UndoRedo works by registering methods and property changes inside "actions". You can create an action, then provide ways to do and undo this action using function calls and property changes, then commit the action. -Common behavior is to create an action, then add do/undo calls to functions or property changes, then committing the action. +When an action is committed, all of the ``do_*`` methods will run. If the :ref:`undo` method is used, the ``undo_*`` methods will run. If the :ref:`redo` method is used, once again, all of the ``do_*`` methods will run. -Here's an example on how to add an UndoRedo action: +Here's an example on how to add an action: .. tabs:: @@ -81,7 +81,7 @@ Here's an example on how to add an UndoRedo action: \ :ref:`create_action`, :ref:`add_do_method`, :ref:`add_undo_method`, :ref:`add_do_property`, :ref:`add_undo_property`, and :ref:`commit_action` should be called one after the other, like in the example. Not doing so could lead to crashes. -If you don't need to register a method, you can leave :ref:`add_do_method` and :ref:`add_undo_method` out; the same goes for properties. You can also register more than one method/property. +If you don't need to register a method, you can leave :ref:`add_do_method` and :ref:`add_undo_method` out; the same goes for properties. You can also register more than one method/property in the order they should run. If you are making an :ref:`EditorPlugin` and want to integrate into the editor's undo history, use :ref:`EditorUndoRedoManager` instead. diff --git a/classes/class_upnp.rst b/classes/class_upnp.rst index fe1978810..3d9126388 100644 --- a/classes/class_upnp.rst +++ b/classes/class_upnp.rst @@ -463,11 +463,11 @@ Adds the given :ref:`UPNPDevice` to the list of discovered dev :ref:`int` **add_port_mapping** **(** :ref:`int` port, :ref:`int` port_internal=0, :ref:`String` desc="", :ref:`String` proto="UDP", :ref:`int` duration=0 **)** |const| -Adds a mapping to forward the external ``port`` (between 1 and 65535, although recommended to use port 1024 or above) on the default gateway (see :ref:`get_gateway`) to the ``internal_port`` on the local machine for the given protocol ``proto`` (either ``"TCP"`` or ``"UDP"``, with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with :ref:`get_gateway` and call :ref:`add_port_mapping` on it, if any. Note that forwarding a well-known port (below 1024) with UPnP may fail depending on the device. +Adds a mapping to forward the external ``port`` (between 1 and 65535, although recommended to use port 1024 or above) on the default gateway (see :ref:`get_gateway`) to the ``port_internal`` on the local machine for the given protocol ``proto`` (either ``"TCP"`` or ``"UDP"``, with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with :ref:`get_gateway` and call :ref:`add_port_mapping` on it, if any. Note that forwarding a well-known port (below 1024) with UPnP may fail depending on the device. Depending on the gateway device, if a mapping for that port already exists, it will either be updated or it will refuse this command due to that conflict, especially if the existing mapping for that port wasn't created via UPnP or points to a different network address (or device) than this one. -If ``internal_port`` is ``0`` (the default), the same port number is used for both the external and the internal port (the ``port`` value). +If ``port_internal`` is ``0`` (the default), the same port number is used for both the external and the internal port (the ``port`` value). The description (``desc``) is shown in some routers management UIs and can be used to point out which application added the mapping. diff --git a/classes/class_variant.rst b/classes/class_variant.rst index b46ca1569..535179489 100644 --- a/classes/class_variant.rst +++ b/classes/class_variant.rst @@ -38,7 +38,7 @@ In computer programming, a Variant class is a class that is designed to store a var boo = "Boo is a string!"; var ref = new RefCounted(); // var is especially useful when used together with a constructor. - // Godot also provides a Variant type that works like an union of all the Variant-compatible types. + // Godot also provides a Variant type that works like a union of all the Variant-compatible types. Variant fooVar = 2; // fooVar is dynamically an integer (stored as a `long` in the Variant type). fooVar = "Now fooVar is a string!"; fooVar = new RefCounted(); // fooVar is a GodotObject. diff --git a/classes/class_vboxcontainer.rst b/classes/class_vboxcontainer.rst index 631ac5852..6f82f8023 100644 --- a/classes/class_vboxcontainer.rst +++ b/classes/class_vboxcontainer.rst @@ -14,21 +14,21 @@ VBoxContainer **Inherited By:** :ref:`ColorPicker`, :ref:`FileSystemDock`, :ref:`ScriptEditorBase` -Vertical box container. +A container that arranges its child controls vertically. .. rst-class:: classref-introduction-group Description ----------- -Vertical box container. See :ref:`BoxContainer`. +A variant of :ref:`BoxContainer` that can only arrange its child controls vertically. Child controls are rearranged automatically when their minimum size changes. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` - `3D Voxel Demo `__ diff --git a/classes/class_vector2.rst b/classes/class_vector2.rst index 02922e2ab..26eef5d3f 100644 --- a/classes/class_vector2.rst +++ b/classes/class_vector2.rst @@ -10,14 +10,14 @@ Vector2 ======= -Vector used for 2D math using floating point coordinates. +A 2D vector using floating point coordinates. .. rst-class:: classref-introduction-group Description ----------- -2-element structure that can be used to represent positions in 2D space or any other pair of numeric values. +A 2-element structure that can be used to represent 2D coordinates or any other pair of numeric values. It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike :ref:`float` which is always 64-bit. If double precision is needed, compile the engine with the option ``precision=double``. @@ -939,6 +939,8 @@ Returns ``true`` if the vectors are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1075,6 +1077,8 @@ Divides each component of the **Vector2** by the given :ref:`int`. Compares two **Vector2** vectors by first checking if the X value of the left vector is less than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1087,6 +1091,8 @@ Compares two **Vector2** vectors by first checking if the X value of the left ve Compares two **Vector2** vectors by first checking if the X value of the left vector is less than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1101,6 +1107,8 @@ Returns ``true`` if the vectors are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1113,6 +1121,8 @@ Returns ``true`` if the vectors are exactly equal. Compares two **Vector2** vectors by first checking if the X value of the left vector is greater than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1125,6 +1135,8 @@ Compares two **Vector2** vectors by first checking if the X value of the left ve Compares two **Vector2** vectors by first checking if the X value of the left vector is greater than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vector2i.rst b/classes/class_vector2i.rst index 21b852d13..e5d07a3b5 100644 --- a/classes/class_vector2i.rst +++ b/classes/class_vector2i.rst @@ -10,14 +10,14 @@ Vector2i ======== -Vector used for 2D math using integer coordinates. +A 2D vector using integer coordinates. .. rst-class:: classref-introduction-group Description ----------- -2-element structure that can be used to represent positions in 2D space or any other pair of numeric values. +A 2-element structure that can be used to represent 2D grid coordinates or any other pair of integers. It uses integer coordinates and is therefore preferable to :ref:`Vector2` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector2` this cannot be configured with an engine build option. Use :ref:`int` or :ref:`PackedInt64Array` if 64-bit values are needed. diff --git a/classes/class_vector3.rst b/classes/class_vector3.rst index 955fa6f10..b197b6583 100644 --- a/classes/class_vector3.rst +++ b/classes/class_vector3.rst @@ -10,14 +10,14 @@ Vector3 ======= -Vector used for 3D math using floating point coordinates. +A 3D vector using floating point coordinates. .. rst-class:: classref-introduction-group Description ----------- -3-element structure that can be used to represent positions in 3D space or any other triplet of numeric values. +A 3-element structure that can be used to represent 3D coordinates or any other triplet of numeric values. It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike :ref:`float` which is always 64-bit. If double precision is needed, compile the engine with the option ``precision=double``. @@ -963,6 +963,8 @@ Returns ``true`` if the vectors are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1123,6 +1125,8 @@ Divides each component of the **Vector3** by the given :ref:`int`. Compares two **Vector3** vectors by first checking if the X value of the left vector is less than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1135,6 +1139,8 @@ Compares two **Vector3** vectors by first checking if the X value of the left ve Compares two **Vector3** vectors by first checking if the X value of the left vector is less than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1149,6 +1155,8 @@ Returns ``true`` if the vectors are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1161,6 +1169,8 @@ Returns ``true`` if the vectors are exactly equal. Compares two **Vector3** vectors by first checking if the X value of the left vector is greater than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1173,6 +1183,8 @@ Compares two **Vector3** vectors by first checking if the X value of the left ve Compares two **Vector3** vectors by first checking if the X value of the left vector is greater than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vector3i.rst b/classes/class_vector3i.rst index df1a8601b..5983c52d3 100644 --- a/classes/class_vector3i.rst +++ b/classes/class_vector3i.rst @@ -10,14 +10,14 @@ Vector3i ======== -Vector used for 3D math using integer coordinates. +A 3D vector using integer coordinates. .. rst-class:: classref-introduction-group Description ----------- -3-element structure that can be used to represent positions in 3D space or any other triplet of numeric values. +A 3-element structure that can be used to represent 3D grid coordinates or any other triplet of integers. It uses integer coordinates and is therefore preferable to :ref:`Vector3` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector3` this cannot be configured with an engine build option. Use :ref:`int` or :ref:`PackedInt64Array` if 64-bit values are needed. diff --git a/classes/class_vector4.rst b/classes/class_vector4.rst index 0d23d53c0..e94e098fa 100644 --- a/classes/class_vector4.rst +++ b/classes/class_vector4.rst @@ -10,14 +10,14 @@ Vector4 ======= -Vector used for 4D math using floating point coordinates. +A 4D vector using floating point coordinates. .. rst-class:: classref-introduction-group Description ----------- -4-element structure that can be used to represent any quadruplet of numeric values. +A 4-element structure that can be used to represent 4D coordinates or any other quadruplet of numeric values. It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike :ref:`float` which is always 64-bit. If double precision is needed, compile the engine with the option ``precision=double``. @@ -680,6 +680,8 @@ Returns ``true`` if the vectors are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -824,6 +826,8 @@ Divides each component of the **Vector4** by the given :ref:`int`. Compares two **Vector4** vectors by first checking if the X value of the left vector is less than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -836,6 +840,8 @@ Compares two **Vector4** vectors by first checking if the X value of the left ve Compares two **Vector4** vectors by first checking if the X value of the left vector is less than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -850,6 +856,8 @@ Returns ``true`` if the vectors are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -862,6 +870,8 @@ Returns ``true`` if the vectors are exactly equal. Compares two **Vector4** vectors by first checking if the X value of the left vector is greater than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -874,6 +884,8 @@ Compares two **Vector4** vectors by first checking if the X value of the left ve Compares two **Vector4** vectors by first checking if the X value of the left vector is greater than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vector4i.rst b/classes/class_vector4i.rst index ff52ff6c5..20bf6b61f 100644 --- a/classes/class_vector4i.rst +++ b/classes/class_vector4i.rst @@ -10,17 +10,19 @@ Vector4i ======== -Vector used for 4D math using integer coordinates. +A 4D vector using integer coordinates. .. rst-class:: classref-introduction-group Description ----------- -4-element structure that can be used to represent 4D grid coordinates or sets of integers. +A 4-element structure that can be used to represent 4D grid coordinates or any other quadruplet of integers. It uses integer coordinates and is therefore preferable to :ref:`Vector4` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector4` this cannot be configured with an engine build option. Use :ref:`int` or :ref:`PackedInt64Array` if 64-bit values are needed. +\ **Note:** In a boolean context, a Vector4i will evaluate to ``false`` if it's equal to ``Vector4i(0, 0, 0, 0)``. Otherwise, a Vector3i will always evaluate to ``true``. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_vflowcontainer.rst b/classes/class_vflowcontainer.rst index 78e68e7c6..08c4ea223 100644 --- a/classes/class_vflowcontainer.rst +++ b/classes/class_vflowcontainer.rst @@ -12,14 +12,21 @@ VFlowContainer **Inherits:** :ref:`FlowContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical flow container. +A container that arranges its child controls vertically and wraps them around at the borders. .. rst-class:: classref-introduction-group Description ----------- -Vertical version of :ref:`FlowContainer`. +A variant of :ref:`FlowContainer` that can only arrange its child controls vertically, wrapping them around at the borders. This is similar to how text in a book wraps around when no more words can fit on a line, except vertically. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_videostreamplayer.rst b/classes/class_videostreamplayer.rst index 9be598a03..aa1b6e130 100644 --- a/classes/class_videostreamplayer.rst +++ b/classes/class_videostreamplayer.rst @@ -12,14 +12,14 @@ VideoStreamPlayer **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control for playing video streams. +A control used for video playback. .. rst-class:: classref-introduction-group Description ----------- -Control node for playing video streams using :ref:`VideoStream` resources. +A control used for playback of :ref:`VideoStream` resources. Supported video formats are `Ogg Theora `__ (``.ogv``, :ref:`VideoStreamTheora`) and any format exposed via a GDExtension plugin. diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index c7b47adb9..ddf87d382 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -14,7 +14,7 @@ Viewport **Inherited By:** :ref:`SubViewport`, :ref:`Window` -Base class for viewports. +Abstract base class for viewports. Encapsulates drawing and interaction with a game world. .. rst-class:: classref-introduction-group @@ -23,7 +23,7 @@ Description A Viewport creates a different view into the screen, or a sub-view inside another viewport. Children 2D Nodes will display on it, and children Camera3D 3D nodes will render on it too. -Optionally, a viewport can have its own 2D or 3D world, so they don't share what they draw with other viewports. +Optionally, a viewport can have its own 2D or 3D world, so it doesn't share what it draws with other viewports. Viewports can also choose to be audio listeners, so they generate positional audio depending on a 2D or 3D camera child of it. diff --git a/classes/class_viewporttexture.rst b/classes/class_viewporttexture.rst index 5cbecf2f9..4f2088498 100644 --- a/classes/class_viewporttexture.rst +++ b/classes/class_viewporttexture.rst @@ -12,18 +12,18 @@ ViewportTexture **Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Texture which displays the content of a :ref:`Viewport`. +Provides the content of a :ref:`Viewport` as a dynamic texture. .. rst-class:: classref-introduction-group Description ----------- -Displays the content of a :ref:`Viewport` node as a dynamic :ref:`Texture2D`. This can be used to mix controls, 2D, and 3D elements in the same scene. +Provides the content of a :ref:`Viewport` as a dynamic :ref:`Texture2D`. This can be used to mix controls, 2D game objects, and 3D game objects in the same scene. -To create a ViewportTexture in code, use the :ref:`Viewport.get_texture` method on the target viewport. +To create a **ViewportTexture** in code, use the :ref:`Viewport.get_texture` method on the target viewport. -\ **Note:** When local to scene, this texture uses :ref:`Resource.setup_local_to_scene` to set the proxy texture and flags in the local viewport. Local to scene viewport textures will return incorrect data until the scene root is ready (see :ref:`Node.ready`). +\ **Note:** When local to scene, this texture uses :ref:`Resource.setup_local_to_scene` to set the proxy texture and flags in the local viewport. Local to scene **ViewportTexture**\ s will return incorrect data until the scene root is ready (see :ref:`Node.ready`). .. rst-class:: classref-introduction-group @@ -70,7 +70,7 @@ Property Descriptions - void **set_viewport_path_in_scene** **(** :ref:`NodePath` value **)** - :ref:`NodePath` **get_viewport_path_in_scene** **(** **)** -The path to the :ref:`Viewport` node to display. This is relative to the scene root, not to the node which uses the texture. +The path to the :ref:`Viewport` node to display. This is relative to the scene root, not to the node that uses the texture. .. |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_visualinstance3d.rst b/classes/class_visualinstance3d.rst index 7151d0626..03dbda457 100644 --- a/classes/class_visualinstance3d.rst +++ b/classes/class_visualinstance3d.rst @@ -89,6 +89,10 @@ This object will only be visible for :ref:`Camera3D`\ s whose cu For :ref:`Light3D`\ s, this can be used to control which **VisualInstance3D**\ s are affected by a specific light. For :ref:`GPUParticles3D`, this can be used to control which particles are effected by a specific attractor. For :ref:`Decal`\ s, this can be used to control which **VisualInstance3D**\ s are affected by a specific decal. +To adjust :ref:`layers` more easily using a script, use :ref:`get_layer_mask_value` and :ref:`set_layer_mask_value`. + +\ **Note:** :ref:`VoxelGI`, SDFGI and :ref:`LightmapGI` will always take all layers into account to determine what contributes to global illumination. If this is an issue, set :ref:`GeometryInstance3D.gi_mode` to :ref:`GeometryInstance3D.GI_MODE_DISABLED` for meshes and :ref:`Light3D.light_bake_mode` to :ref:`Light3D.BAKE_DISABLED` for lights to exclude them from global illumination. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vscrollbar.rst b/classes/class_vscrollbar.rst index ece710f7c..226390225 100644 --- a/classes/class_vscrollbar.rst +++ b/classes/class_vscrollbar.rst @@ -12,14 +12,14 @@ VScrollBar **Inherits:** :ref:`ScrollBar` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical scroll bar. +A vertical scrollbar that goes from top (min) to bottom (max). .. rst-class:: classref-introduction-group Description ----------- -Vertical version of :ref:`ScrollBar`, which goes from top (min) to bottom (max). +A vertical scrollbar, typically used to navigate through content that extends beyond the visible height of a control. It is a :ref:`Range`-based control and goes from top (min) to bottom (max). Note that this direction is the opposite of :ref:`VSlider`'s. .. rst-class:: classref-reftable-group diff --git a/classes/class_vseparator.rst b/classes/class_vseparator.rst index 59bbdbe81..233f4e6e5 100644 --- a/classes/class_vseparator.rst +++ b/classes/class_vseparator.rst @@ -12,14 +12,14 @@ VSeparator **Inherits:** :ref:`Separator` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical version of :ref:`Separator`. +A vertical line used for separating other controls. .. rst-class:: classref-introduction-group Description ----------- -Vertical version of :ref:`Separator`. Even though it looks vertical, it is used to separate objects horizontally. +A vertical separator used for separating other controls that are arranged **horizontally**. **VSeparator** is purely visual and normally drawn as a :ref:`StyleBoxLine`. .. rst-class:: classref-reftable-group diff --git a/classes/class_vslider.rst b/classes/class_vslider.rst index 8bed895a2..5c5acceea 100644 --- a/classes/class_vslider.rst +++ b/classes/class_vslider.rst @@ -12,16 +12,14 @@ VSlider **Inherits:** :ref:`Slider` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical slider. +A vertical slider that goes from bottom (min) to top (max). .. rst-class:: classref-introduction-group Description ----------- -Vertical slider. See :ref:`Slider`. This one goes from bottom (min) to top (max). - -\ **Note:** The :ref:`Range.changed` and :ref:`Range.value_changed` signals are part of the :ref:`Range` class which this class inherits from. +A vertical slider, used to adjust a value by moving a grabber along a vertical axis. It is a :ref:`Range`-based control and goes from bottom (min) to top (max). Note that this direction is the opposite of :ref:`VScrollBar`'s. .. rst-class:: classref-reftable-group diff --git a/classes/class_vsplitcontainer.rst b/classes/class_vsplitcontainer.rst index fc61a5d8d..cb61b4497 100644 --- a/classes/class_vsplitcontainer.rst +++ b/classes/class_vsplitcontainer.rst @@ -12,21 +12,21 @@ VSplitContainer **Inherits:** :ref:`SplitContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical split container. +A container that splits two child controls vertically and provides a grabber for adjusting the split ratio. .. rst-class:: classref-introduction-group Description ----------- -Vertical split container. See :ref:`SplitContainer`. This goes from top to bottom. +A container that accepts only two child controls, then arranges them vertically and creates a divisor between them. The divisor can be dragged around to change the size relation between the child controls. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_weakref.rst b/classes/class_weakref.rst index f086f83b6..9e6a2bfbe 100644 --- a/classes/class_weakref.rst +++ b/classes/class_weakref.rst @@ -12,14 +12,14 @@ WeakRef **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Holds an :ref:`Object`, but does not contribute to the reference count if the object is a reference. +Holds an :ref:`Object`. If the object is :ref:`RefCounted`, it doesn't update the reference count. .. rst-class:: classref-introduction-group Description ----------- -A weakref can hold a :ref:`RefCounted`, without contributing to the reference counter. A weakref can be created from an :ref:`Object` using :ref:`@GlobalScope.weakref`. If this object is not a reference, weakref still works, however, it does not have any effect on the object. Weakrefs are useful in cases where multiple classes have variables that refer to each other. Without weakrefs, using these classes could lead to memory leaks, since both references keep each other from being released. Making part of the variables a weakref can prevent this cyclic dependency, and allows the references to be released. +A weakref can hold a :ref:`RefCounted` without contributing to the reference counter. A weakref can be created from an :ref:`Object` using :ref:`@GlobalScope.weakref`. If this object is not a reference, weakref still works, however, it does not have any effect on the object. Weakrefs are useful in cases where multiple classes have variables that refer to each other. Without weakrefs, using these classes could lead to memory leaks, since both references keep each other from being released. Making part of the variables a weakref can prevent this cyclic dependency, and allows the references to be released. .. rst-class:: classref-reftable-group diff --git a/classes/class_webrtcmultiplayerpeer.rst b/classes/class_webrtcmultiplayerpeer.rst index e85b4ee5a..74f2601ec 100644 --- a/classes/class_webrtcmultiplayerpeer.rst +++ b/classes/class_webrtcmultiplayerpeer.rst @@ -70,7 +70,7 @@ Method Descriptions Add a new peer to the mesh with the given ``peer_id``. The :ref:`WebRTCPeerConnection` must be in state :ref:`WebRTCPeerConnection.STATE_NEW`. -Three channels will be created for reliable, unreliable, and ordered transport. The value of ``unreliable_lifetime`` will be passed to the ``maxPacketLifetime`` option when creating unreliable and ordered channels (see :ref:`WebRTCPeerConnection.create_data_channel`). +Three channels will be created for reliable, unreliable, and ordered transport. The value of ``unreliable_lifetime`` will be passed to the ``"maxPacketLifetime"`` option when creating unreliable and ordered channels (see :ref:`WebRTCPeerConnection.create_data_channel`). .. rst-class:: classref-item-separator @@ -122,7 +122,7 @@ You can optionally specify a ``channels_config`` array of :ref:`TransferMode` **get_peer** **(** :ref:`int` peer_id **)** -Returns a dictionary representation of the peer with given ``peer_id`` with three keys. ``connection`` containing the :ref:`WebRTCPeerConnection` to this peer, ``channels`` an array of three :ref:`WebRTCDataChannel`, and ``connected`` a boolean representing if the peer connection is currently connected (all three channels are open). +Returns a dictionary representation of the peer with given ``peer_id`` with three keys. ``"connection"`` containing the :ref:`WebRTCPeerConnection` to this peer, ``"channels"`` an array of three :ref:`WebRTCDataChannel`, and ``"connected"`` a boolean representing if the peer connection is currently connected (all three channels are open). .. rst-class:: classref-item-separator diff --git a/classes/class_webrtcpeerconnection.rst b/classes/class_webrtcpeerconnection.rst index 0397c94a9..f27246996 100644 --- a/classes/class_webrtcpeerconnection.rst +++ b/classes/class_webrtcpeerconnection.rst @@ -308,7 +308,7 @@ Close the peer connection and all data channels associated with it. Returns a new :ref:`WebRTCDataChannel` (or ``null`` on failure) with given ``label`` and optionally configured via the ``options`` dictionary. This method can only be called when the connection is in state :ref:`STATE_NEW`. -There are two ways to create a working data channel: either call :ref:`create_data_channel` on only one of the peer and listen to :ref:`data_channel_received` on the other, or call :ref:`create_data_channel` on both peers, with the same values, and the ``negotiated`` option set to ``true``. +There are two ways to create a working data channel: either call :ref:`create_data_channel` on only one of the peer and listen to :ref:`data_channel_received` on the other, or call :ref:`create_data_channel` on both peers, with the same values, and the ``"negotiated"`` option set to ``true``. Valid ``options`` are: @@ -388,9 +388,9 @@ Returns the :ref:`SignalingState` on t :ref:`Error` **initialize** **(** :ref:`Dictionary` configuration={} **)** -Re-initialize this peer connection, closing any previously active connection, and going back to state :ref:`STATE_NEW`. A dictionary of ``options`` can be passed to configure the peer connection. +Re-initialize this peer connection, closing any previously active connection, and going back to state :ref:`STATE_NEW`. A dictionary of ``configuration`` options can be passed to configure the peer connection. -Valid ``options`` are: +Valid ``configuration`` options are: :: @@ -457,9 +457,9 @@ After calling this function the peer will start emitting :ref:`ice_candidate_cre Sets the SDP description of the remote peer. This should be called with the values generated by a remote peer and received over the signaling server. -If ``type`` is ``offer`` the peer will emit :ref:`session_description_created` with the appropriate answer. +If ``type`` is ``"offer"`` the peer will emit :ref:`session_description_created` with the appropriate answer. -If ``type`` is ``answer`` the peer will start emitting :ref:`ice_candidate_created`. +If ``type`` is ``"answer"`` the peer will start emitting :ref:`ice_candidate_created`. .. |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_window.rst b/classes/class_window.rst index 5f5684d2e..24da41d19 100644 --- a/classes/class_window.rst +++ b/classes/class_window.rst @@ -14,7 +14,7 @@ Window **Inherited By:** :ref:`AcceptDialog`, :ref:`Popup` -Base class for all windows. +Base class for all windows, dialogs, and popups. .. rst-class:: classref-introduction-group @@ -23,7 +23,7 @@ Description A node that creates a window. The window can either be a native system window or embedded inside another **Window** (see :ref:`Viewport.gui_embed_subwindows`). -At runtime, **Window**\ s will not close automatically when requested. You need to handle it manually using :ref:`close_requested` (this applies both to clicking close button and clicking outside popup). +At runtime, **Window**\ s will not close automatically when requested. You need to handle it manually using the :ref:`close_requested` signal (this applies both to pressing the close button and clicking outside of a popup). .. rst-class:: classref-reftable-group @@ -1923,9 +1923,7 @@ Moves the **Window** on top of other windows and focuses it. void **popup** **(** :ref:`Rect2i` rect=Rect2i(0, 0, 0, 0) **)** -Shows the **Window** and makes it transient (see :ref:`transient`). If ``rect`` is provided, it will be set as the **Window**'s size. - -Fails if called on the main window. +Shows the **Window** and makes it transient (see :ref:`transient`). If ``rect`` is provided, it will be set as the **Window**'s size. Fails if called on the main window. .. rst-class:: classref-item-separator @@ -1937,9 +1935,7 @@ Fails if called on the main window. void **popup_centered** **(** :ref:`Vector2i` minsize=Vector2i(0, 0) **)** -Popups the **Window** at the center of the current screen, with optionally given minimum size. - -If the **Window** is embedded, it will be centered in the parent :ref:`Viewport` instead. +Popups the **Window** at the center of the current screen, with optionally given minimum size. If the **Window** is embedded, it will be centered in the parent :ref:`Viewport` instead. \ **Note:** Calling it with the default value of ``minsize`` is equivalent to calling it with :ref:`size`. @@ -1953,9 +1949,7 @@ If the **Window** is embedded, it will be centered in the parent :ref:`Viewport< void **popup_centered_clamped** **(** :ref:`Vector2i` minsize=Vector2i(0, 0), :ref:`float` fallback_ratio=0.75 **)** -Popups the **Window** centered inside its parent **Window**. - -\ ``fallback_ratio`` determines the maximum size of the **Window**, in relation to its parent. +Popups the **Window** centered inside its parent **Window**. ``fallback_ratio`` determines the maximum size of the **Window**, in relation to its parent. \ **Note:** Calling it with the default value of ``minsize`` is equivalent to calling it with :ref:`size`. @@ -1981,9 +1975,7 @@ Popups the **Window** centered inside its parent **Window** and sets its size as void **popup_on_parent** **(** :ref:`Rect2i` parent_rect **)** -Popups the **Window** with a position shifted by parent **Window**'s position. - -If the **Window** is embedded, has the same effect as :ref:`popup`. +Popups the **Window** with a position shifted by parent **Window**'s position. If the **Window** is embedded, has the same effect as :ref:`popup`. .. rst-class:: classref-item-separator diff --git a/classes/class_world2d.rst b/classes/class_world2d.rst index b052ec2a1..e5760b690 100644 --- a/classes/class_world2d.rst +++ b/classes/class_world2d.rst @@ -12,14 +12,14 @@ World2D **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Class that has everything pertaining to a 2D world. +A resource that holds all components of a 2D world, such as a canvas and a physics space. .. rst-class:: classref-introduction-group Description ----------- -Class that has everything pertaining to a 2D world. A physics space, a visual scenario and a sound space. 2D nodes register their resources into the current 2D world. +Class that has everything pertaining to a 2D world: A physics space, a canvas, and a sound space. 2D nodes register their resources into the current 2D world. .. rst-class:: classref-introduction-group diff --git a/classes/class_world3d.rst b/classes/class_world3d.rst index 184688757..7953c1167 100644 --- a/classes/class_world3d.rst +++ b/classes/class_world3d.rst @@ -12,14 +12,14 @@ World3D **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Class that has everything pertaining to a world. +A resource that holds all components of a 3D world, such as a visual scenario and a physics space. .. rst-class:: classref-introduction-group Description ----------- -Class that has everything pertaining to a world. A physics space, a visual scenario and a sound space. Node3D nodes register their resources into the current world. +Class that has everything pertaining to a world: A physics space, a visual scenario, and a sound space. 3D nodes register their resources into the current 3D world. .. rst-class:: classref-introduction-group diff --git a/classes/class_xmlparser.rst b/classes/class_xmlparser.rst index 18b506d33..37f21e495 100644 --- a/classes/class_xmlparser.rst +++ b/classes/class_xmlparser.rst @@ -12,6 +12,8 @@ XMLParser **Inherits:** :ref:`RefCounted` **<** :ref:`Object` +Provides a low-level interface for creating parsers for XML files. + Low-level class for creating parsers for `XML `__ files. .. rst-class:: classref-introduction-group @@ -19,7 +21,7 @@ Low-level class for creating parsers for `XML `__ files. This class can serve as base to make custom XML parsers. .. rst-class:: classref-reftable-group