From b69855897aff6d1d65c4ab741ca53b697ab066ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Sat, 8 Oct 2022 13:57:16 +0200 Subject: [PATCH] classref: Sync with current master branch (bbac8198f) --- classes/class_@gdscript.rst | 14 +- classes/class_@globalscope.rst | 16 +- classes/class_aescontext.rst | 1 + classes/class_animatedsprite2d.rst | 14 +- classes/class_animatedsprite3d.rst | 16 +- classes/class_animationlibrary.rst | 2 +- classes/class_animationnodeblendtree.rst | 9 + ...ss_animationnodestatemachinetransition.rst | 52 +- classes/class_animationplayer.rst | 12 +- classes/class_animationtree.rst | 9 + classes/class_array.rst | 276 ++- classes/class_astargrid2d.rst | 20 +- classes/class_atlastexture.rst | 16 +- classes/class_audiostreamplayer3d.rst | 38 +- classes/class_basematerial3d.rst | 2 +- classes/class_basis.rst | 2 +- classes/class_callable.rst | 10 + classes/class_camera2d.rst | 160 +- classes/class_canvasitem.rst | 14 +- classes/class_collisionshape2d.rst | 38 +- classes/class_colorpicker.rst | 96 +- classes/class_control.rst | 30 +- classes/class_cubemap.rst | 4 +- classes/class_cubemaparray.rst | 11 + classes/class_diraccess.rst | 481 +++++ classes/class_directory.rst | 381 ---- classes/class_displayserver.rst | 80 +- classes/class_editorimportplugin.rst | 6 +- classes/class_editorinspector.rst | 16 + classes/class_editornode3dgizmo.rst | 26 +- classes/class_editornode3dgizmoplugin.rst | 4 +- classes/class_editorplugin.rst | 48 +- classes/class_editorproperty.rst | 10 + classes/class_editorscenepostimport.rst | 2 +- classes/class_editorscript.rst | 2 +- classes/class_editorsettings.rst | 10 +- .../class_editortranslationparserplugin.rst | 4 +- classes/class_engine.rst | 114 +- classes/class_environment.rst | 24 +- .../{class_file.rst => class_fileaccess.rst} | 443 ++-- classes/class_filesystemdock.rst | 2 +- classes/class_fogmaterial.rst | 14 +- classes/class_fogvolume.rst | 10 +- classes/class_font.rst | 12 +- classes/class_geometry2d.rst | 12 +- classes/class_gltfdocumentextension.rst | 45 +- classes/class_gltfnode.rst | 10 + classes/class_gltfstate.rst | 164 +- classes/class_gltftexture.rst | 24 +- classes/class_gltftexturesampler.rst | 105 + classes/class_gridmap.rst | 2 +- classes/class_hmaccontext.rst | 18 +- classes/class_hslider.rst | 44 +- classes/class_image.rst | 2 - classes/class_imageformatloader.rst | 48 + classes/class_imageformatloaderextension.rst | 75 + classes/class_imagetexturelayered.rst | 12 + classes/class_inputeventwithmodifiers.rst | 2 +- classes/class_json.rst | 52 +- classes/class_lightmapgi.rst | 12 +- classes/class_menubutton.rst | 10 + classes/class_multiplayerapiextension.rst | 2 +- classes/class_multiplayersynchronizer.rst | 4 +- classes/class_navigationobstacle2d.rst | 2 +- classes/class_navigationobstacle3d.rst | 2 +- .../class_navigationpathqueryparameters2d.rst | 164 ++ .../class_navigationpathqueryparameters3d.rst | 164 ++ classes/class_navigationpathqueryresult2d.rst | 67 + classes/class_navigationpathqueryresult3d.rst | 67 + classes/class_navigationregion2d.rst | 2 + classes/class_navigationregion3d.rst | 2 + classes/class_navigationserver2d.rst | 10 + classes/class_navigationserver3d.rst | 10 + classes/class_node.rst | 36 +- classes/class_node2d.rst | 4 + classes/class_node3d.rst | 10 +- classes/class_openxrhand.rst | 124 ++ classes/class_optionbutton.rst | 10 + classes/class_os.rst | 78 +- classes/class_packedbytearray.rst | 6 +- classes/class_packedscene.rst | 4 +- classes/class_panoramaskymaterial.rst | 4 +- classes/class_physicsbody2d.rst | 30 +- classes/class_physicsbody3d.rst | 38 +- classes/class_physicsdirectbodystate3d.rst | 14 + ...lass_physicsdirectbodystate3dextension.rst | 8 + classes/class_physicsserver2d.rst | 20 + classes/class_physicsserver2dextension.rst | 20 +- classes/class_physicsserver3d.rst | 20 + classes/class_physicsserver3dextension.rst | 20 +- .../class_physicstestmotionparameters2d.rst | 4 +- .../class_physicstestmotionparameters3d.rst | 4 +- classes/class_planemesh.rst | 6 +- classes/class_projectsettings.rst | 778 +++++-- classes/class_quadmesh.rst | 43 + classes/class_quaternion.rst | 2 +- classes/class_refcounted.rst | 26 +- classes/class_resource.rst | 2 +- classes/class_resourcesaver.rst | 4 +- classes/class_scripteditorbase.rst | 20 +- classes/class_staticbody2d.rst | 2 +- classes/class_staticbody3d.rst | 2 +- classes/class_streampeer.rst | 2 +- classes/class_streampeerbuffer.rst | 2 +- classes/class_streampeergzip.rst | 75 + classes/class_textedit.rst | 724 ++++--- classes/class_textserver.rst | 4 + classes/class_textserverextension.rst | 1924 +++++++---------- classes/class_texture2darray.rst | 7 + classes/class_texturelayered.rst | 18 +- classes/class_tilemap.rst | 6 +- classes/class_tree.rst | 18 + classes/class_treeitem.rst | 22 + classes/class_tween.rst | 217 +- classes/class_undoredo.rst | 12 +- classes/class_viewport.rst | 44 + classes/class_vslider.rst | 44 +- classes/class_window.rst | 54 +- classes/class_world2d.rst | 2 +- classes/class_world3d.rst | 2 +- classes/class_xrinterface.rst | 42 + classes/class_xrinterfaceextension.rst | 54 + 122 files changed, 5387 insertions(+), 2909 deletions(-) create mode 100644 classes/class_diraccess.rst delete mode 100644 classes/class_directory.rst rename classes/{class_file.rst => class_fileaccess.rst} (63%) create mode 100644 classes/class_gltftexturesampler.rst create mode 100644 classes/class_imageformatloader.rst create mode 100644 classes/class_imageformatloaderextension.rst create mode 100644 classes/class_navigationpathqueryparameters2d.rst create mode 100644 classes/class_navigationpathqueryparameters3d.rst create mode 100644 classes/class_navigationpathqueryresult2d.rst create mode 100644 classes/class_navigationpathqueryresult3d.rst create mode 100644 classes/class_openxrhand.rst create mode 100644 classes/class_quadmesh.rst create mode 100644 classes/class_streampeergzip.rst diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index e2b336341..c4b1bba0d 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -328,7 +328,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE` to add subgroups to your groups. @@ -397,7 +397,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT`'s ready state change. Values for these properties are no assigned immediately upon the node's creation, and instead are computed and stored right before :ref:`Node._ready`. +Mark the following property as assigned on :ref:`Node`'s ready state change. Values for these properties are not assigned immediately upon the node's creation, and instead are computed and stored right before :ref:`Node._ready`. :: @@ -592,7 +592,7 @@ Converts a ``dictionary`` (previously created with :ref:`inst_to_dict` **get_stack** **(** **)** -Returns an array of dictionaries representing the current call stack. +Returns an array of dictionaries representing the current call stack. See also :ref:`print_stack`. :: @@ -611,6 +611,8 @@ would print [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}] +\ **Note:** :ref:`get_stack` only works if the running instance is connected to a debugging server (i.e. an editor instance). :ref:`get_stack` will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server. + \ **Note:** Not supported for calling from threads. Instead, this will return an empty array. ---- @@ -710,7 +712,7 @@ Output in the console would look something like this: - void **print_stack** **(** **)** -Prints a stack trace at the current code location. Only works when running with debugger turned on. +Prints a stack trace at the current code location. See also :ref:`get_stack`. Output in the console would look something like this: @@ -718,6 +720,8 @@ Output in the console would look something like this: Frame 0 - res://test.gd:16 in function '_process' +\ **Note:** :ref:`print_stack` only works if the running instance is connected to a debugging server (i.e. an editor instance). :ref:`print_stack` will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server. + \ **Note:** Not supported for calling from threads. Instead of the stack trace, this will print the thread ID. ---- diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 4701dc4eb..74e7ac228 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -1621,9 +1621,9 @@ enum **MouseButton**: - **MOUSE_BUTTON_NONE** = **0** --- Enum value which doesn't correspond to any mouse button. This is used to initialize :ref:`MouseButton` properties with a generic state. -- **MOUSE_BUTTON_LEFT** = **1** --- Left mouse button. +- **MOUSE_BUTTON_LEFT** = **1** --- Primary mouse button, usually the left button. -- **MOUSE_BUTTON_RIGHT** = **2** --- Right mouse button. +- **MOUSE_BUTTON_RIGHT** = **2** --- Secondary mouse button, usually the right button. - **MOUSE_BUTTON_MIDDLE** = **3** --- Middle mouse button. @@ -1639,9 +1639,9 @@ enum **MouseButton**: - **MOUSE_BUTTON_XBUTTON2** = **9** --- Extra mouse button 2 (only present on some mice). -- **MOUSE_BUTTON_MASK_LEFT** = **1** --- Left mouse button mask. +- **MOUSE_BUTTON_MASK_LEFT** = **1** --- Primary mouse button mask, usually for the left button. -- **MOUSE_BUTTON_MASK_RIGHT** = **2** --- Right mouse button mask. +- **MOUSE_BUTTON_MASK_RIGHT** = **2** --- Secondary mouse button mask, usually for the right button. - **MOUSE_BUTTON_MASK_MIDDLE** = **4** --- Middle mouse button mask. @@ -2200,11 +2200,11 @@ enum **PropertyHint**: - **PROPERTY_HINT_RANGE** = **1** --- Hints that an integer or float property should be within a range specified via the hint string ``"min,max"`` or ``"min,max,step"``. The hint string can optionally include ``"or_greater"`` and/or ``"or_less"`` to allow manual input going respectively above the max or below the min values. Example: ``"-360,360,1,or_greater,or_less"``. -Additionally, other keywords can be included: ``"exp"`` for exponential range editing, ``"radians"`` for editing radian angles in degrees, ``"degrees"`` to hint at an angle and ``"no_slider"`` to hide the slider. +Additionally, other keywords can be included: ``"exp"`` for exponential range editing, ``"radians"`` for editing radian angles in degrees, ``"degrees"`` to hint at an angle and ``"hide_slider"`` to hide the slider. - **PROPERTY_HINT_ENUM** = **2** --- Hints that an integer, float or string property is an enumerated value to pick in a list specified via a hint string. -The hint string is a comma separated list of names such as ``"Hello,Something,Else"``. For integer and float properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"Zero,One,Three:3,Four,Six:6"``. +The hint string is a comma separated list of names such as ``"Hello,Something,Else"``. Whitespaces are **not** removed from either end of a name. For integer and float properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"Zero,One,Three:3,Four,Six:6"``. - **PROPERTY_HINT_ENUM_SUGGESTION** = **3** --- Hints that a string property can be an enumerated value to pick in a list specified via a hint string such as ``"Hello,Something,Else"``. @@ -2367,6 +2367,8 @@ Unlike :ref:`PROPERTY_HINT_ENUM` .. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_BASIC_SETTING: +.. _class_@GlobalScope_constant_PROPERTY_USAGE_READ_ONLY: + .. _class_@GlobalScope_constant_PROPERTY_USAGE_ARRAY: .. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFAULT: @@ -2433,6 +2435,8 @@ enum **PropertyUsageFlags**: - **PROPERTY_USAGE_EDITOR_BASIC_SETTING** = **134217728** +- **PROPERTY_USAGE_READ_ONLY** = **268435456** --- The property is read-only in the editor inspector. + - **PROPERTY_USAGE_ARRAY** = **536870912** - **PROPERTY_USAGE_DEFAULT** = **6** --- Default usage (storage, editor and network). diff --git a/classes/class_aescontext.rst b/classes/class_aescontext.rst index 8a7e39902..5e1e19348 100644 --- a/classes/class_aescontext.rst +++ b/classes/class_aescontext.rst @@ -63,6 +63,7 @@ This class provides access to AES encryption/decryption of raw data. Both AES-EC public class Example : Node { public AESContext Aes = new AESContext(); + public override void _Ready() { string key = "My secret key!!!"; // Key must be either 16 or 32 bytes. diff --git a/classes/class_animatedsprite2d.rst b/classes/class_animatedsprite2d.rst index eb02f874a..78170382a 100644 --- a/classes/class_animatedsprite2d.rst +++ b/classes/class_animatedsprite2d.rst @@ -19,6 +19,10 @@ Description ``AnimatedSprite2D`` is similar to the :ref:`Sprite2D` node, except it carries multiple textures as animation frames. Animations are created using a :ref:`SpriteFrames` resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The :ref:`SpriteFrames` resource can be configured in the editor via the SpriteFrames bottom panel. +After setting up :ref:`frames`, :ref:`play` may be called. It's also possible to select an :ref:`animation` and toggle :ref:`playing`, even within the editor. + +To pause the current animation, call :ref:`stop` or set :ref:`playing` to ``false``. Alternatively, setting :ref:`speed_scale` to ``0`` also preserves the current frame's elapsed time. + \ **Note:** You can associate a set of normal or specular maps by creating additional :ref:`SpriteFrames` resources with a ``_normal`` or ``_specular`` suffix. For example, having 3 :ref:`SpriteFrames` resources ``run``, ``run_normal``, and ``run_specular`` will make it so the ``run`` animation uses normal and specular maps. Tutorials @@ -202,7 +206,7 @@ The texture's drawing offset. | *Getter* | is_playing() | +-----------+--------------------+ -If ``true``, the :ref:`animation` is currently playing. +If ``true``, the :ref:`animation` is currently playing. Setting this property to ``false`` is the equivalent of calling :ref:`stop`. ---- @@ -218,7 +222,7 @@ If ``true``, the :ref:`animation` is | *Getter* | get_speed_scale() | +-----------+------------------------+ -The animation speed is multiplied by this value. +The animation speed is multiplied by this value. If set to a negative value, the animation is played in reverse. If set to ``0``, the animation is paused, preserving the current frame's elapsed time. Method Descriptions ------------------- @@ -227,7 +231,7 @@ Method Descriptions - void **play** **(** :ref:`StringName` anim=&"", :ref:`bool` backwards=false **)** -Plays the animation named ``anim``. If no ``anim`` is provided, the current animation is played. If ``backwards`` is ``true``, the animation will be played in reverse. +Plays the animation named ``anim``. If no ``anim`` is provided, the current animation is played. If ``backwards`` is ``true``, the animation is played in reverse. ---- @@ -235,7 +239,9 @@ Plays the animation named ``anim``. If no ``anim`` is provided, the current anim - void **stop** **(** **)** -Stops the current animation (does not reset the frame counter). +Stops the current :ref:`animation` at the current :ref:`frame`. + +\ **Note:** This method resets the current frame's elapsed time. If this behavior is undesired, consider setting :ref:`speed_scale` to ``0``, instead. .. |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_animatedsprite3d.rst b/classes/class_animatedsprite3d.rst index 90a8567b0..e3535addc 100644 --- a/classes/class_animatedsprite3d.rst +++ b/classes/class_animatedsprite3d.rst @@ -17,7 +17,11 @@ AnimatedSprite3D Description ----------- -Animations are created using a :ref:`SpriteFrames` resource, which can be configured in the editor via the SpriteFrames panel. +``AnimatedSprite3D`` is similar to the :ref:`Sprite3D` node, except it carries multiple textures as animation :ref:`frames`. Animations are created using a :ref:`SpriteFrames` resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The :ref:`SpriteFrames` resource can be configured in the editor via the SpriteFrames bottom panel. + +After setting up :ref:`frames`, :ref:`play` may be called. It's also possible to select an :ref:`animation` and toggle :ref:`playing`, even within the editor. + +To pause the current animation, call :ref:`stop` or set :ref:`playing` to ``false``. Alternatively, setting :ref:`speed_scale` to ``0`` also preserves the current frame's elapsed time. Tutorials --------- @@ -126,7 +130,7 @@ The :ref:`SpriteFrames` resource containing the animation(s) | *Getter* | is_playing() | +-----------+--------------------+ -If ``true``, the :ref:`animation` is currently playing. +If ``true``, the :ref:`animation` is currently playing. Setting this property to ``false`` is the equivalent of calling :ref:`stop`. ---- @@ -142,7 +146,7 @@ If ``true``, the :ref:`animation` is | *Getter* | get_speed_scale() | +-----------+------------------------+ -The animation speed is multiplied by this value. +The animation speed is multiplied by this value. If set to a negative value, the animation is played in reverse. If set to ``0``, the animation is paused, preserving the current frame's elapsed time. Method Descriptions ------------------- @@ -151,7 +155,7 @@ Method Descriptions - void **play** **(** :ref:`StringName` anim=&"", :ref:`bool` backwards=false **)** -Plays the animation named ``anim``. If no ``anim`` is provided, the current animation is played. If ``backwards`` is ``true``, the animation will be played in reverse. +Plays the animation named ``anim``. If no ``anim`` is provided, the current animation is played. If ``backwards`` is ``true``, the animation is played in reverse. ---- @@ -159,7 +163,9 @@ Plays the animation named ``anim``. If no ``anim`` is provided, the current anim - void **stop** **(** **)** -Stops the current animation (does not reset the frame counter). +Stops the current :ref:`animation` at the current :ref:`frame`. + +\ **Note:** This method resets the current frame's elapsed time. If this behavior is undesired, consider setting :ref:`speed_scale` to ``0``, instead. .. |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_animationlibrary.rst b/classes/class_animationlibrary.rst index 0a02e741d..54e247d57 100644 --- a/classes/class_animationlibrary.rst +++ b/classes/class_animationlibrary.rst @@ -91,7 +91,7 @@ Method Descriptions - :ref:`Error` **add_animation** **(** :ref:`StringName` name, :ref:`Animation` animation **)** -Adds the ``animation`` to the library, accesible by the key ``name``. +Adds the ``animation`` to the library, accessible by the key ``name``. ---- diff --git a/classes/class_animationnodeblendtree.rst b/classes/class_animationnodeblendtree.rst index 976a227dd..4b14067a5 100644 --- a/classes/class_animationnodeblendtree.rst +++ b/classes/class_animationnodeblendtree.rst @@ -56,6 +56,15 @@ Methods | void | :ref:`set_node_position` **(** :ref:`StringName` name, :ref:`Vector2` position **)** | +-------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +Signals +------- + +.. _class_AnimationNodeBlendTree_signal_node_changed: + +- **node_changed** **(** :ref:`StringName` node_name **)** + +Emitted when the input port information is changed. + Constants --------- diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index 94f3fb8fb..a97b6f7fd 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -22,25 +22,23 @@ Tutorials Properties ---------- -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`StringName` | :ref:`advance_condition` | ``&""`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`String` | :ref:`advance_expression` | ``""`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`NodePath` | :ref:`advance_expression_base_node` | ``NodePath("")`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`bool` | :ref:`auto_advance` | ``false`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`int` | :ref:`priority` | ``1`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`SwitchMode` | :ref:`switch_mode` | ``0`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`Curve` | :ref:`xfade_curve` | | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ -| :ref:`float` | :ref:`xfade_time` | ``0.0`` | -+------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+------------------+ ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`StringName` | :ref:`advance_condition` | ``&""`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`String` | :ref:`advance_expression` | ``""`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`bool` | :ref:`auto_advance` | ``false`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`bool` | :ref:`disabled` | ``false`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`int` | :ref:`priority` | ``1`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`SwitchMode` | :ref:`switch_mode` | ``0`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`Curve` | :ref:`xfade_curve` | | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ +| :ref:`float` | :ref:`xfade_time` | ``0.0`` | ++------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ Signals ------- @@ -118,22 +116,6 @@ Use an expression as a condition for state machine transitions. It is possible t ---- -.. _class_AnimationNodeStateMachineTransition_property_advance_expression_base_node: - -- :ref:`NodePath` **advance_expression_base_node** - -+-----------+-----------------------------------------+ -| *Default* | ``NodePath("")`` | -+-----------+-----------------------------------------+ -| *Setter* | set_advance_expression_base_node(value) | -+-----------+-----------------------------------------+ -| *Getter* | get_advance_expression_base_node() | -+-----------+-----------------------------------------+ - -The path to the :ref:`Node` used to evaluate an :ref:`Expression` if one is not explicitly specified internally. - ----- - .. _class_AnimationNodeStateMachineTransition_property_auto_advance: - :ref:`bool` **auto_advance** diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index 02501804f..696b2688f 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -19,7 +19,7 @@ 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. -Some methods and properties use a single key to refence an animation directly. These keys are formatted as the key for the library, followed by a forward slash, then the key for the animation whithin 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. +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. @@ -145,6 +145,14 @@ Notifies when an animation finished playing. ---- +.. _class_AnimationPlayer_signal_animation_list_changed: + +- **animation_list_changed** **(** **)** + +Notifies when an animation list is changed. + +---- + .. _class_AnimationPlayer_signal_animation_started: - **animation_started** **(** :ref:`StringName` anim_name **)** @@ -578,7 +586,7 @@ Queues an animation for playback once the current one is done. - void **remove_animation_library** **(** :ref:`StringName` name **)** -Removes the :ref:`AnimationLibrary` assosiated with the key ``name``. +Removes the :ref:`AnimationLibrary` associated with the key ``name``. ---- diff --git a/classes/class_animationtree.rst b/classes/class_animationtree.rst index 2ac3c2d6c..d7d1ffa7b 100644 --- a/classes/class_animationtree.rst +++ b/classes/class_animationtree.rst @@ -56,6 +56,15 @@ Methods | void | :ref:`rename_parameter` **(** :ref:`String` old_name, :ref:`String` new_name **)** | +---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ +Signals +------- + +.. _class_AnimationTree_signal_animation_player_changed: + +- **animation_player_changed** **(** **)** + +Emitted when the :ref:`anim_player` is changed. + Enumerations ------------ diff --git a/classes/class_array.rst b/classes/class_array.rst index 0e4823c38..c27f613e8 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -71,110 +71,128 @@ Arrays can be concatenated using the ``+`` operator: Constructors ------------ -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedByteArray` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedColorArray` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedFloat32Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedFloat64Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedInt32Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedInt64Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedStringArray` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedVector2Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`Array` **(** :ref:`PackedVector3Array` from **)** | -+---------------------------+------------------------------------------------------------------------------------------------------------------+ ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`Array` base, :ref:`int` type, :ref:`StringName` class_name, :ref:`Variant` script **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedByteArray` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedColorArray` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedFloat32Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedFloat64Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedInt32Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedInt64Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedStringArray` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedVector2Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`Array` **(** :ref:`PackedVector3Array` from **)** | ++---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Methods ------- -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`all` **(** :ref:`Callable` method **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`any` **(** :ref:`Callable` method **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`append` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`append_array` **(** :ref:`Array` array **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`back` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`bsearch` **(** :ref:`Variant` value, :ref:`bool` before=true **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`bsearch_custom` **(** :ref:`Variant` value, :ref:`Callable` func, :ref:`bool` before=true **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`clear` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`count` **(** :ref:`Variant` value **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`duplicate` **(** :ref:`bool` deep=false **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`erase` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`fill` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`filter` **(** :ref:`Callable` method **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`find` **(** :ref:`Variant` what, :ref:`int` from=0 **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`find_last` **(** :ref:`Variant` value **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`front` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`has` **(** :ref:`Variant` value **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`hash` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`insert` **(** :ref:`int` position, :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_empty` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`map` **(** :ref:`Callable` method **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`max` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`min` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`pop_at` **(** :ref:`int` position **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`pop_back` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`pop_front` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`push_back` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`push_front` **(** :ref:`Variant` value **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`reduce` **(** :ref:`Callable` method, :ref:`Variant` accum=null **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_at` **(** :ref:`int` position **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`resize` **(** :ref:`int` size **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`reverse` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`rfind` **(** :ref:`Variant` what, :ref:`int` from=-1 **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`shuffle` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`size` **(** **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Array` | :ref:`slice` **(** :ref:`int` begin, :ref:`int` end=2147483647, :ref:`int` step=1, :ref:`bool` deep=false **)** |const| | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`sort` **(** **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`sort_custom` **(** :ref:`Callable` func **)** | -+-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`all` **(** :ref:`Callable` method **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`any` **(** :ref:`Callable` method **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`append` **(** :ref:`Variant` value **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`append_array` **(** :ref:`Array` array **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`back` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`bsearch` **(** :ref:`Variant` value, :ref:`bool` before=true **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`bsearch_custom` **(** :ref:`Variant` value, :ref:`Callable` func, :ref:`bool` before=true **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`clear` **(** **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`count` **(** :ref:`Variant` value **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`duplicate` **(** :ref:`bool` deep=false **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`erase` **(** :ref:`Variant` value **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`fill` **(** :ref:`Variant` value **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`filter` **(** :ref:`Callable` method **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`find` **(** :ref:`Variant` what, :ref:`int` from=0 **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`find_last` **(** :ref:`Variant` value **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`front` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_typed_builtin` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`StringName` | :ref:`get_typed_class_name` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`get_typed_script` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`has` **(** :ref:`Variant` value **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`hash` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`insert` **(** :ref:`int` position, :ref:`Variant` value **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_empty` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_read_only` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_typed` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`map` **(** :ref:`Callable` method **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`max` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`min` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`pop_at` **(** :ref:`int` position **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`pop_back` **(** **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`pop_front` **(** **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`push_back` **(** :ref:`Variant` value **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`push_front` **(** :ref:`Variant` value **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`reduce` **(** :ref:`Callable` method, :ref:`Variant` accum=null **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`remove_at` **(** :ref:`int` position **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`resize` **(** :ref:`int` size **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`reverse` **(** **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`rfind` **(** :ref:`Variant` what, :ref:`int` from=-1 **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_read_only` **(** :ref:`bool` enable **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`set_typed` **(** :ref:`int` type, :ref:`StringName` class_name, :ref:`Variant` script **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`shuffle` **(** **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`size` **(** **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Array` | :ref:`slice` **(** :ref:`int` begin, :ref:`int` end=2147483647, :ref:`int` step=1, :ref:`bool` deep=false **)** |const| | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`sort` **(** **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`sort_custom` **(** :ref:`Callable` func **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`typed_assign` **(** :ref:`Array` array **)** | ++-------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Operators --------- @@ -208,6 +226,10 @@ Constructs an empty ``Array``. ---- +- :ref:`Array` **Array** **(** :ref:`Array` base, :ref:`int` type, :ref:`StringName` class_name, :ref:`Variant` script **)** + +---- + - :ref:`Array` **Array** **(** :ref:`Array` from **)** Constructs an ``Array`` as a copy of the given ``Array``. @@ -490,6 +512,24 @@ Returns the first element of the array. Prints an error and returns ``null`` if ---- +.. _class_Array_method_get_typed_builtin: + +- :ref:`int` **get_typed_builtin** **(** **)** |const| + +---- + +.. _class_Array_method_get_typed_class_name: + +- :ref:`StringName` **get_typed_class_name** **(** **)** |const| + +---- + +.. _class_Array_method_get_typed_script: + +- :ref:`Variant` **get_typed_script** **(** **)** |const| + +---- + .. _class_Array_method_has: - :ref:`bool` **has** **(** :ref:`Variant` value **)** |const| @@ -573,6 +613,18 @@ Returns ``true`` if the array is empty. ---- +.. _class_Array_method_is_read_only: + +- :ref:`bool` **is_read_only** **(** **)** |const| + +---- + +.. _class_Array_method_is_typed: + +- :ref:`bool` **is_typed** **(** **)** |const| + +---- + .. _class_Array_method_map: - :ref:`Array` **map** **(** :ref:`Callable` method **)** |const| @@ -713,6 +765,18 @@ Searches the array in reverse order. Optionally, a start search index can be pas ---- +.. _class_Array_method_set_read_only: + +- void **set_read_only** **(** :ref:`bool` enable **)** + +---- + +.. _class_Array_method_set_typed: + +- void **set_typed** **(** :ref:`int` type, :ref:`StringName` class_name, :ref:`Variant` script **)** + +---- + .. _class_Array_method_shuffle: - void **shuffle** **(** **)** @@ -751,6 +815,8 @@ If ``deep`` is true, each element will be copied by value rather than by referen Sorts the array. +\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when using :ref:`sort`. + \ **Note:** Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example: @@ -784,7 +850,9 @@ To perform natural order sorting, you can use :ref:`sort_custom`__. This means that values considered equal may have their order changed when using :ref:`sort_custom`. + +\ **Note:** You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior. .. tabs:: @@ -811,6 +879,12 @@ Sorts the array using a custom method. The custom method receives two arguments +---- + +.. _class_Array_method_typed_assign: + +- :ref:`bool` **typed_assign** **(** :ref:`Array` array **)** + Operator Descriptions --------------------- diff --git a/classes/class_astargrid2d.rst b/classes/class_astargrid2d.rst index a3f11d372..d20fa27d8 100644 --- a/classes/class_astargrid2d.rst +++ b/classes/class_astargrid2d.rst @@ -21,7 +21,10 @@ Compared to :ref:`AStar2D` you don't need to manually create poin In contrast to :ref:`AStar2D`, you only need set the :ref:`size` of the grid, optionally set the :ref:`cell_size` and then call the :ref:`update` method: -:: + +.. tabs:: + + .. code-tab:: gdscript var astar_grid = AStarGrid2D.new() astar_grid.size = Vector2i(32, 32) @@ -30,6 +33,17 @@ In contrast to :ref:`AStar2D`, you only need set the :ref:`size` **(** **)** | +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedVector2Array` | :ref:`get_id_path` **(** :ref:`Vector2i` from_id, :ref:`Vector2i` to_id **)** | +| :ref:`Vector2i[]` | :ref:`get_id_path` **(** :ref:`Vector2i` from_id, :ref:`Vector2i` to_id **)** | +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedVector2Array` | :ref:`get_point_path` **(** :ref:`Vector2i` from_id, :ref:`Vector2i` to_id **)** | +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -282,7 +296,7 @@ Clears the grid and sets the :ref:`size` to :re .. _class_AStarGrid2D_method_get_id_path: -- :ref:`PackedVector2Array` **get_id_path** **(** :ref:`Vector2i` from_id, :ref:`Vector2i` to_id **)** +- :ref:`Vector2i[]` **get_id_path** **(** :ref:`Vector2i` from_id, :ref:`Vector2i` to_id **)** Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. diff --git a/classes/class_atlastexture.rst b/classes/class_atlastexture.rst index d52345d4f..e73d410a9 100644 --- a/classes/class_atlastexture.rst +++ b/classes/class_atlastexture.rst @@ -12,14 +12,16 @@ AtlasTexture **Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Crops out one part of a texture, such as a texture from a texture atlas. +A texture that crops out part of another Texture2D. Description ----------- -:ref:`Texture2D` resource that crops out one part of the :ref:`atlas` texture, defined by :ref:`region`. The main use case is cropping out textures from a texture atlas, which is a big texture file that packs multiple smaller textures. Consists of a :ref:`Texture2D` for the :ref:`atlas`, a :ref:`region` that defines the area of :ref:`atlas` to use, and a :ref:`margin` that defines the border width. +:ref:`Texture2D` resource that draws only part of its :ref:`atlas` texture, as defined by the :ref:`region`. An additional :ref:`margin` can also be set, which is useful for small adjustments. -\ ``AtlasTexture`` cannot be used in an :ref:`AnimatedTexture`, cannot be tiled in nodes such as :ref:`TextureRect`, and does not work properly if used inside of other ``AtlasTexture`` resources. Multiple ``AtlasTexture`` resources can be used to crop multiple textures from the atlas. Using a texture atlas helps to optimize video memory costs and render calls compared to using multiple small files. +Multiple ``AtlasTexture`` resources can be cropped from the same :ref:`atlas`. Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls. + +\ **Note:** ``AtlasTexture`` cannot be used in an :ref:`AnimatedTexture`, and may not tile properly in nodes such as :ref:`TextureRect`, when inside other ``AtlasTexture`` resources. Properties ---------- @@ -47,7 +49,7 @@ Property Descriptions | *Getter* | get_atlas() | +----------+------------------+ -The texture that contains the atlas. Can be any :ref:`Texture2D` subtype. +The texture that contains the atlas. Can be any type inheriting from :ref:`Texture2D`, including another ``AtlasTexture``. ---- @@ -63,7 +65,7 @@ The texture that contains the atlas. Can be any :ref:`Texture2D | *Getter* | has_filter_clip() | +-----------+------------------------+ -If ``true``, clips the area outside of the region to avoid bleeding of the surrounding texture pixels. +If ``true``, the area outside of the :ref:`region` is clipped to avoid bleeding of the surrounding texture pixels. ---- @@ -79,7 +81,7 @@ If ``true``, clips the area outside of the region to avoid bleeding of the surro | *Getter* | get_margin() | +-----------+-----------------------+ -The margin around the region. The :ref:`Rect2`'s :ref:`Rect2.size` parameter ("w" and "h" in the editor) resizes the texture so it fits within the margin. +The margin around the :ref:`region`. Useful for small adjustments. If the :ref:`Rect2.size` of this property ("w" and "h" in the editor) is set, the drawn texture is resized to fit within the margin. ---- @@ -95,7 +97,7 @@ The margin around the region. The :ref:`Rect2`'s :ref:`Rect2.size`. .. |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_audiostreamplayer3d.rst b/classes/class_audiostreamplayer3d.rst index 5c82cd83a..61e44eadb 100644 --- a/classes/class_audiostreamplayer3d.rst +++ b/classes/class_audiostreamplayer3d.rst @@ -23,7 +23,7 @@ By default, audio is heard from the camera position. This can be changed by addi See also :ref:`AudioStreamPlayer` to play a sound non-positionally. -\ **Note:** Hiding an ``AudioStreamPlayer3D`` node does not disable its audio output. To temporarily disable an ``AudioStreamPlayer3D``'s audio output, set :ref:`unit_db` to a very low value like ``-100`` (which isn't audible to human hearing). +\ **Note:** Hiding an ``AudioStreamPlayer3D`` node does not disable its audio output. To temporarily disable an ``AudioStreamPlayer3D``'s audio output, set :ref:`volume_db` to a very low value like ``-100`` (which isn't audible to human hearing). Tutorials --------- @@ -70,10 +70,10 @@ Properties +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ | :ref:`bool` | :ref:`stream_paused` | ``false`` | +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ -| :ref:`float` | :ref:`unit_db` | ``0.0`` | -+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ | :ref:`float` | :ref:`unit_size` | ``10.0`` | +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ +| :ref:`float` | :ref:`volume_db` | ``0.0`` | ++--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ Methods ------- @@ -429,22 +429,6 @@ If ``true``, the playback is paused. You can resume it by setting :ref:`stream_p ---- -.. _class_AudioStreamPlayer3D_property_unit_db: - -- :ref:`float` **unit_db** - -+-----------+--------------------+ -| *Default* | ``0.0`` | -+-----------+--------------------+ -| *Setter* | set_unit_db(value) | -+-----------+--------------------+ -| *Getter* | get_unit_db() | -+-----------+--------------------+ - -The base sound level unaffected by dampening, in decibels. - ----- - .. _class_AudioStreamPlayer3D_property_unit_size: - :ref:`float` **unit_size** @@ -459,6 +443,22 @@ The base sound level unaffected by dampening, in decibels. The factor for the attenuation effect. Higher values make the sound audible over a larger distance. +---- + +.. _class_AudioStreamPlayer3D_property_volume_db: + +- :ref:`float` **volume_db** + ++-----------+----------------------+ +| *Default* | ``0.0`` | ++-----------+----------------------+ +| *Setter* | set_volume_db(value) | ++-----------+----------------------+ +| *Getter* | get_volume_db() | ++-----------+----------------------+ + +The base sound level unaffected by dampening, in decibels. + Method Descriptions ------------------- diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index f9fad38fc..ccd664bb5 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -2691,7 +2691,7 @@ Returns ``true``, if the specified flag is enabled. See :ref:`Flags` **get_texture** **(** :ref:`TextureParam` param **)** |const| -Returns the :ref:`Texture` associated with the specified :ref:`TextureParam`. +Returns the :ref:`Texture2D` associated with the specified :ref:`TextureParam`. ---- diff --git a/classes/class_basis.rst b/classes/class_basis.rst index 877f453ab..849308ac8 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -270,7 +270,7 @@ Constructs a pure scale basis matrix with no rotation or shearing. The scale val - :ref:`Vector3` **get_euler** **(** :ref:`int` order=2 **)** |const| -Returns the basis's rotation in the form of Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last). The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle). +Returns the basis's rotation in the form of Euler angles. The Euler order depends on the ``order`` parameter, by default it uses the YXZ convention: when decomposing, first Z, then X, and Y last. The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle). Consider using the :ref:`get_rotation_quaternion` method instead, which returns a :ref:`Quaternion` quaternion instead of Euler angles. diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 1978a9d47..f1ef88dfb 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -71,6 +71,8 @@ Methods +-------------------------------------+-------------------------------------------------------------------------------------------------------------+ | void | :ref:`call_deferred` **(** ... **)** |vararg| |const| | +-------------------------------------+-------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`callv` **(** :ref:`Array` arguments **)** |const| | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`get_method` **(** **)** |const| | +-------------------------------------+-------------------------------------------------------------------------------------------------------------+ | :ref:`Object` | :ref:`get_object` **(** **)** |const| | @@ -156,6 +158,14 @@ Calls the method represented by this ``Callable`` in deferred mode, i.e. during ---- +.. _class_Callable_method_callv: + +- :ref:`Variant` **callv** **(** :ref:`Array` arguments **)** |const| + +Calls the method represented by this ``Callable``. Contrary to :ref:`call`, this method does not take a variable number of arguments but expects all arguments to be passed via a single :ref:`Array`. + +---- + .. _class_Callable_method_get_method: - :ref:`StringName` **get_method** **(** **)** |const| diff --git a/classes/class_camera2d.rst b/classes/class_camera2d.rst index 5142deeff..736cebbc8 100644 --- a/classes/class_camera2d.rst +++ b/classes/class_camera2d.rst @@ -37,57 +37,61 @@ Tutorials Properties ---------- -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`AnchorMode` | :ref:`anchor_mode` | ``1`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`current` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`Node` | :ref:`custom_viewport` | | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`drag_bottom_margin` | ``0.2`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`drag_horizontal_enabled` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`drag_horizontal_offset` | ``0.0`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`drag_left_margin` | ``0.2`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`drag_right_margin` | ``0.2`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`drag_top_margin` | ``0.2`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`drag_vertical_enabled` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`drag_vertical_offset` | ``0.0`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`editor_draw_drag_margin` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`editor_draw_limits` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`editor_draw_screen` | ``true`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`int` | :ref:`limit_bottom` | ``10000000`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`int` | :ref:`limit_left` | ``-10000000`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`int` | :ref:`limit_right` | ``10000000`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`limit_smoothed` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`int` | :ref:`limit_top` | ``-10000000`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`Camera2DProcessCallback` | :ref:`process_callback` | ``1`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`rotating` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`bool` | :ref:`smoothing_enabled` | ``false`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`float` | :ref:`smoothing_speed` | ``5.0`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ -| :ref:`Vector2` | :ref:`zoom` | ``Vector2(1, 1)`` | -+-----------------------------------------------------------------------+---------------------------------------------------------------------------------+-------------------+ ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`AnchorMode` | :ref:`anchor_mode` | ``1`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`current` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`Node` | :ref:`custom_viewport` | | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`drag_bottom_margin` | ``0.2`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`drag_horizontal_enabled` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`drag_horizontal_offset` | ``0.0`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`drag_left_margin` | ``0.2`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`drag_right_margin` | ``0.2`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`drag_top_margin` | ``0.2`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`drag_vertical_enabled` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`drag_vertical_offset` | ``0.0`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`editor_draw_drag_margin` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`editor_draw_limits` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`editor_draw_screen` | ``true`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`ignore_rotation` | ``true`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`int` | :ref:`limit_bottom` | ``10000000`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`int` | :ref:`limit_left` | ``-10000000`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`int` | :ref:`limit_right` | ``10000000`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`limit_smoothed` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`int` | :ref:`limit_top` | ``-10000000`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`Vector2` | :ref:`offset` | ``Vector2(0, 0)`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`Camera2DProcessCallback` | :ref:`process_callback` | ``1`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`rotation_smoothing_enabled` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`rotation_smoothing_speed` | ``5.0`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`bool` | :ref:`smoothing_enabled` | ``false`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`float` | :ref:`smoothing_speed` | ``5.0`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ +| :ref:`Vector2` | :ref:`zoom` | ``Vector2(1, 1)`` | ++-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ Methods ------- @@ -370,6 +374,22 @@ If ``true``, draws the camera's screen rectangle in the editor. ---- +.. _class_Camera2D_property_ignore_rotation: + +- :ref:`bool` **ignore_rotation** + ++-----------+----------------------------+ +| *Default* | ``true`` | ++-----------+----------------------------+ +| *Setter* | set_ignore_rotation(value) | ++-----------+----------------------------+ +| *Getter* | is_ignoring_rotation() | ++-----------+----------------------------+ + +If ``true``, the camera's rendered view is not affected by its :ref:`Node2D.rotation` and :ref:`Node2D.global_rotation`. + +---- + .. _class_Camera2D_property_limit_bottom: - :ref:`int` **limit_bottom** @@ -486,19 +506,37 @@ The camera's process callback. See :ref:`Camera2DProcessCallback` **rotating** +- :ref:`bool` **rotation_smoothing_enabled** -+-----------+---------------------+ -| *Default* | ``false`` | -+-----------+---------------------+ -| *Setter* | set_rotating(value) | -+-----------+---------------------+ -| *Getter* | is_rotating() | -+-----------+---------------------+ ++-----------+---------------------------------------+ +| *Default* | ``false`` | ++-----------+---------------------------------------+ +| *Setter* | set_rotation_smoothing_enabled(value) | ++-----------+---------------------------------------+ +| *Getter* | is_rotation_smoothing_enabled() | ++-----------+---------------------------------------+ -If ``true``, the camera view rotates with the target. +If ``true``, the camera's view smoothly rotates, via asymptotic smoothing, to align with its target rotation at :ref:`rotation_smoothing_speed`. + +\ **Note:** This property has no effect if :ref:`ignore_rotation` is ``true``. + +---- + +.. _class_Camera2D_property_rotation_smoothing_speed: + +- :ref:`float` **rotation_smoothing_speed** + ++-----------+-------------------------------------+ +| *Default* | ``5.0`` | ++-----------+-------------------------------------+ +| *Setter* | set_rotation_smoothing_speed(value) | ++-----------+-------------------------------------+ +| *Getter* | get_rotation_smoothing_speed() | ++-----------+-------------------------------------+ + +The angular, asymptotic speed of the camera's rotation smoothing effect when :ref:`rotation_smoothing_enabled` is ``true``. ---- diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index d5ba3a805..bec5a6c30 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -328,6 +328,8 @@ Property Descriptions | *Getter* | is_clipping_children() | +-----------+--------------------------+ +Allows the current node to clip children nodes, essentially acting as a mask. + ---- .. _class_CanvasItem_property_light_mask: @@ -724,17 +726,17 @@ Draws ``text`` using the specified ``font`` at the ``pos`` (bottom-left corner u # If using this method in a script that redraws constantly, move the # `default_font` declaration to a member variable assigned in `_ready()` # so the Control is only created once. - var default_font = Control.new().get_font("font") - var default_font_size = Control.new().get_font_size("font_size") - draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, font_size) + var default_font = ThemeDB.fallback_font + var default_font_size = ThemeDB.fallback_font_size + draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, default_font_size) .. code-tab:: csharp // If using this method in a script that redraws constantly, move the - // `default_font` declaration to a member variable assigned in `_ready()` + // `default_font` declaration to a member variable assigned in `_Ready()` // so the Control is only created once. - Font defaultFont = new Control().GetFont("font"); - int defaultFontSize = new Control().GetFontSize("font_size"); + Font defaultFont = ThemeDB.FallbackFont; + int defaultFontSize = ThemeDB.FallbackFontSize; DrawString(defaultFont, new Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, defaultFontSize); diff --git a/classes/class_collisionshape2d.rst b/classes/class_collisionshape2d.rst index 8479efbcf..9618d0edd 100644 --- a/classes/class_collisionshape2d.rst +++ b/classes/class_collisionshape2d.rst @@ -35,19 +35,39 @@ Tutorials Properties ---------- -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`disabled` | ``false`` | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`one_way_collision` | ``false`` | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`float` | :ref:`one_way_collision_margin` | ``1.0`` | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ -| :ref:`Shape2D` | :ref:`shape` | | -+-------------------------------+-------------------------------------------------------------------------------------------+-----------+ ++-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ +| :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 1)`` | ++-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ +| :ref:`bool` | :ref:`disabled` | ``false`` | ++-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ +| :ref:`bool` | :ref:`one_way_collision` | ``false`` | ++-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ +| :ref:`float` | :ref:`one_way_collision_margin` | ``1.0`` | ++-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ +| :ref:`Shape2D` | :ref:`shape` | | ++-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ Property Descriptions --------------------- +.. _class_CollisionShape2D_property_debug_color: + +- :ref:`Color` **debug_color** + ++-----------+------------------------+ +| *Default* | ``Color(0, 0, 0, 1)`` | ++-----------+------------------------+ +| *Setter* | set_debug_color(value) | ++-----------+------------------------+ +| *Getter* | get_debug_color() | ++-----------+------------------------+ + +The collision shape debug color. + +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 1)`` value documented here is a placeholder, and not the actual default debug color. + +---- + .. _class_CollisionShape2D_property_disabled: - :ref:`bool` **disabled** diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index 91f8eeaed..6050b9f1f 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -50,13 +50,19 @@ Properties Methods ------- -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_preset` **(** :ref:`Color` color **)** | -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| void | :ref:`erase_preset` **(** :ref:`Color` color **)** | -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| :ref:`PackedColorArray` | :ref:`get_presets` **(** **)** |const| | -+-------------------------------------------------+--------------------------------------------------------------------------------------------------------+ ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`add_preset` **(** :ref:`Color` color **)** | ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`add_recent_preset` **(** :ref:`Color` color **)** | ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`erase_preset` **(** :ref:`Color` color **)** | ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`erase_recent_preset` **(** :ref:`Color` color **)** | ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedColorArray` | :ref:`get_presets` **(** **)** |const| | ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedColorArray` | :ref:`get_recent_presets` **(** **)** |const| | ++-------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ Theme Properties ---------------- @@ -78,6 +84,10 @@ Theme Properties +-----------------------------------+--------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`color_hue` | | +-----------------------------------+--------------------------------------------------------------------------------+---------+ +| :ref:`Texture2D` | :ref:`expanded_arrow` | | ++-----------------------------------+--------------------------------------------------------------------------------+---------+ +| :ref:`Texture2D` | :ref:`folded_arrow` | | ++-----------------------------------+--------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`overbright_indicator` | | +-----------------------------------+--------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`picker_cursor` | | @@ -86,6 +96,12 @@ Theme Properties +-----------------------------------+--------------------------------------------------------------------------------+---------+ | :ref:`Texture2D` | :ref:`screen_picker` | | +-----------------------------------+--------------------------------------------------------------------------------+---------+ +| :ref:`Texture2D` | :ref:`shape_circle` | | ++-----------------------------------+--------------------------------------------------------------------------------+---------+ +| :ref:`Texture2D` | :ref:`shape_rect` | | ++-----------------------------------+--------------------------------------------------------------------------------+---------+ +| :ref:`Texture2D` | :ref:`shape_rect_wheel` | | ++-----------------------------------+--------------------------------------------------------------------------------+---------+ Signals ------- @@ -287,6 +303,16 @@ Adds the given color to a list of color presets. The presets are displayed in th ---- +.. _class_ColorPicker_method_add_recent_preset: + +- void **add_recent_preset** **(** :ref:`Color` color **)** + +Adds the given color to a list of color recent presets so that it can be picked later. Recent presets are the colors that were picked recently, a new preset is automatically created and added to recent presets when you pick a new color. + +\ **Note:** The recent presets list is only for *this* color picker. + +---- + .. _class_ColorPicker_method_erase_preset: - void **erase_preset** **(** :ref:`Color` color **)** @@ -295,12 +321,28 @@ Removes the given color from the list of color presets of this color picker. ---- +.. _class_ColorPicker_method_erase_recent_preset: + +- void **erase_recent_preset** **(** :ref:`Color` color **)** + +Removes the given color from the list of color recent presets of this color picker. + +---- + .. _class_ColorPicker_method_get_presets: - :ref:`PackedColorArray` **get_presets** **(** **)** |const| Returns the list of colors in the presets of the color picker. +---- + +.. _class_ColorPicker_method_get_recent_presets: + +- :ref:`PackedColorArray` **get_recent_presets** **(** **)** |const| + +Returns the list of colors in the recent presets of the color picker. + Theme Property Descriptions --------------------------- @@ -386,6 +428,22 @@ Custom texture for the hue selection slider on the right. ---- +.. _class_ColorPicker_theme_icon_expanded_arrow: + +- :ref:`Texture2D` **expanded_arrow** + +The icon for color preset drop down menu when expanded. + +---- + +.. _class_ColorPicker_theme_icon_folded_arrow: + +- :ref:`Texture2D` **folded_arrow** + +The icon for color preset drop down menu when folded. + +---- + .. _class_ColorPicker_theme_icon_overbright_indicator: - :ref:`Texture2D` **overbright_indicator** @@ -412,6 +470,30 @@ The indicator used to signalize that the color value is outside the 0-1 range. The icon for the screen color picker button. +---- + +.. _class_ColorPicker_theme_icon_shape_circle: + +- :ref:`Texture2D` **shape_circle** + +The icon for circular picker shapes. + +---- + +.. _class_ColorPicker_theme_icon_shape_rect: + +- :ref:`Texture2D` **shape_rect** + +The icon for rectangular picker shapes. + +---- + +.. _class_ColorPicker_theme_icon_shape_rect_wheel: + +- :ref:`Texture2D` **shape_rect_wheel** + +The icon for rectangular wheel picker shapes. + .. |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_control.rst b/classes/class_control.rst index 3aa480972..398dff877 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -25,13 +25,13 @@ For more information on Godot's UI system, anchors, offsets, and containers, see \ **User Interface nodes and input**\ -Godot sends input events to the scene's root node first, by calling :ref:`Node._input`. :ref:`Node._input` forwards the event down the node tree to the nodes under the mouse cursor, or on keyboard focus. To do so, it calls ``MainLoop._input_event``. +Godot propagates input events via viewports. Each :ref:`Viewport` is responsible for propagating :ref:`InputEvent`\ s to their child nodes. As the :ref:`SceneTree.root` is a :ref:`Window`, this already happens automatically for all UI elements in your game. -\ **FIXME:** No longer valid after DisplayServer split and Input refactoring. +Input events are propagated through the :ref:`SceneTree` from the root node to all child nodes by calling :ref:`Node._input`. For UI elements specifically, it makes more sense to override the virtual method :ref:`_gui_input`, which filters out unrelated input events, such as by checking z-order, :ref:`mouse_filter`, focus, or if the event was inside of the control's bounding box. Call :ref:`accept_event` so no other node receives the event. Once you accept an input, it becomes handled so :ref:`Node._unhandled_input` will not process it. -Only one ``Control`` node can be in keyboard focus. Only the node in focus will receive keyboard events. To get the focus, call :ref:`grab_focus`. ``Control`` nodes lose focus when another node grabs it, or if you hide the node in focus. +Only one ``Control`` node can be in focus. Only the node in focus will receive events. To get the focus, call :ref:`grab_focus`. ``Control`` nodes lose focus when another node grabs it, or if you hide the node in focus. Sets :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` to tell a ``Control`` node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. @@ -307,7 +307,7 @@ Signals - **focus_entered** **(** **)** -Emitted when the node gains keyboard focus. +Emitted when the node gains focus. ---- @@ -315,7 +315,7 @@ Emitted when the node gains keyboard focus. - **focus_exited** **(** **)** -Emitted when the node loses keyboard focus. +Emitted when the node loses focus. ---- @@ -402,7 +402,7 @@ enum **FocusMode**: - **FOCUS_CLICK** = **1** --- The node can only grab focus on mouse clicks. Use with :ref:`focus_mode`. -- **FOCUS_ALL** = **2** --- The node can grab focus on mouse click or using the arrows and the Tab keys on the keyboard. Use with :ref:`focus_mode`. +- **FOCUS_ALL** = **2** --- The node can grab focus on mouse click, using the arrows and the Tab keys on the keyboard, or using the D-pad buttons on a gamepad. Use with :ref:`focus_mode`. ---- @@ -866,7 +866,7 @@ The minimum size of the node's bounding rectangle. If you set it to a value grea | *Getter* | get_focus_mode() | +-----------+-----------------------+ -The focus access mode for the control (None, Click or All). Only one Control can be focused at the same time, and it will receive keyboard signals. +The focus access mode for the control (None, Click or All). Only one Control can be focused at the same time, and it will receive keyboard, gamepad, and mouse signals. ---- @@ -882,7 +882,7 @@ The focus access mode for the control (None, Click or All). Only one Control can | *Getter* | get_focus_neighbor() | +-----------+---------------------------+ -Tells Godot which node it should give keyboard focus to if the user presses the down arrow on the keyboard or down on a gamepad by default. You can change the key by editing the ``ui_down`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the bottom of this one. +Tells Godot which node it should give focus to if the user presses the down arrow on the keyboard or down on a gamepad by default. You can change the key by editing the ``ui_down`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the bottom of this one. ---- @@ -898,7 +898,7 @@ Tells Godot which node it should give keyboard focus to if the user presses the | *Getter* | get_focus_neighbor() | +-----------+---------------------------+ -Tells Godot which node it should give keyboard focus to if the user presses the left arrow on the keyboard or left on a gamepad by default. You can change the key by editing the ``ui_left`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the left of this one. +Tells Godot which node it should give focus to if the user presses the left arrow on the keyboard or left on a gamepad by default. You can change the key by editing the ``ui_left`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the left of this one. ---- @@ -914,7 +914,7 @@ Tells Godot which node it should give keyboard focus to if the user presses the | *Getter* | get_focus_neighbor() | +-----------+---------------------------+ -Tells Godot which node it should give keyboard focus to if the user presses the right arrow on the keyboard or right on a gamepad by default. You can change the key by editing the ``ui_right`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the bottom of this one. +Tells Godot which node it should give focus to if the user presses the right arrow on the keyboard or right on a gamepad by default. You can change the key by editing the ``ui_right`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the bottom of this one. ---- @@ -930,7 +930,7 @@ Tells Godot which node it should give keyboard focus to if the user presses the | *Getter* | get_focus_neighbor() | +-----------+---------------------------+ -Tells Godot which node it should give keyboard focus to if the user presses the top arrow on the keyboard or top on a gamepad by default. You can change the key by editing the ``ui_top`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the bottom of this one. +Tells Godot which node it should give focus to if the user presses the top arrow on the keyboard or top on a gamepad by default. You can change the key by editing the ``ui_top`` input action. The node must be a ``Control``. If this property is not set, Godot will give focus to the closest ``Control`` to the bottom of this one. ---- @@ -946,7 +946,7 @@ Tells Godot which node it should give keyboard focus to if the user presses the | *Getter* | get_focus_next() | +-----------+-----------------------+ -Tells Godot which node it should give keyboard focus to if the user presses :kbd:`Tab` on a keyboard by default. You can change the key by editing the ``ui_focus_next`` input action. +Tells Godot which node it should give focus to if the user presses :kbd:`Tab` on a keyboard by default. You can change the key by editing the ``ui_focus_next`` input action. If this property is not set, Godot will select a "best guess" based on surrounding nodes in the scene tree. @@ -964,7 +964,7 @@ If this property is not set, Godot will select a "best guess" based on surroundi | *Getter* | get_focus_previous() | +-----------+---------------------------+ -Tells Godot which node it should give keyboard focus to if the user presses :kbd:`Shift + Tab` on a keyboard by default. You can change the key by editing the ``ui_focus_prev`` input action. +Tells Godot which node it should give focus to if the user presses :kbd:`Shift + Tab` on a keyboard by default. You can change the key by editing the ``ui_focus_prev`` input action. If this property is not set, Godot will select a "best guess" based on surrounding nodes in the scene tree. @@ -1998,7 +1998,7 @@ See :ref:`get_theme_color` for details. Returns the tooltip text ``at_position`` in local coordinates, which will typically appear when the cursor is resting over this control. By default, it returns :ref:`tooltip_text`. -\ **Note:** This method can be overriden to customise its behaviour. If this method returns an empty :ref:`String`, no tooltip is displayed. +\ **Note:** This method can be overridden to customise its behaviour. If this method returns an empty :ref:`String`, no tooltip is displayed. ---- @@ -2187,7 +2187,7 @@ Returns ``true`` if layout is right-to-left. - void **release_focus** **(** **)** -Give up the focus. No other control will be able to receive keyboard input. +Give up the focus. No other control will be able to receive input. ---- diff --git a/classes/class_cubemap.rst b/classes/class_cubemap.rst index d1920d00d..bb43ddf40 100644 --- a/classes/class_cubemap.rst +++ b/classes/class_cubemap.rst @@ -17,11 +17,11 @@ Cubemap Description ----------- -A cubemap is a 6-sided texture typically used for faking reflections in 3D rendering. It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods. +A cubemap is made of 6 textures organized in layers. They are typically used for faking reflections (see :ref:`ReflectionProbe`) in 3D rendering. It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods. This resource is typically used as a uniform in custom shaders. Few core Godot methods make use of Cubemap resources. -\ **Note:** Godot doesn't support using cubemaps as a :ref:`PanoramaSkyMaterial`. You can use `this tool `__ to convert a cube map to an equirectangular sky map. +\ **Note:** Godot doesn't support using cubemaps in a :ref:`PanoramaSkyMaterial`. You can use `this tool `__ to convert a cubemap to an equirectangular sky map. .. |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_cubemaparray.rst b/classes/class_cubemaparray.rst index cd9fb489d..f8463accd 100644 --- a/classes/class_cubemaparray.rst +++ b/classes/class_cubemaparray.rst @@ -12,7 +12,18 @@ CubemapArray **Inherits:** :ref:`ImageTextureLayered` **<** :ref:`TextureLayered` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` +A single composite texture resource which consists of multiple :ref:`Cubemap`\ s. +Description +----------- + +``CubemapArray``\ s are made of an array of :ref:`Cubemap`\ s. Accordingly, like :ref:`Cubemap`\ s they are made of multiple textures the amount of which must be divisible by 6 (one image for each face of the cube). The primary benefit of ``CubemapArray``\ s is that they can be accessed in shader code using a single texture reference. In other words, you can pass multiple :ref:`Cubemap`\ s into a shader using a single ``CubemapArray``. + +Generally, ``CubemapArray``\ s provide a more efficient way for storing multiple :ref:`Cubemap`\ s, than storing multiple :ref:`Cubemap`\ s themselves in an array. + +Internally Godot, uses ``CubemapArray``\ s for many effects including the :ref:`Sky`, if you set :ref:`ProjectSettings.rendering/reflections/sky_reflections/texture_array_reflections` to ``true``. + +\ **Note:** ``CubemapArray`` is not supported in the OpenGL 3 rendering backend. .. |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_diraccess.rst b/classes/class_diraccess.rst new file mode 100644 index 000000000..73c18b5ae --- /dev/null +++ b/classes/class_diraccess.rst @@ -0,0 +1,481 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/DirAccess.xml. + +.. _class_DirAccess: + +DirAccess +========= + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +Type used to handle the filesystem. + +Description +----------- + +Directory type. It is used to manage directories and their content (not restricted to 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. + +Most of the methods have a static alternative that can be used without creating a ``DirAccess``. Static methods only support absolute paths (including ``res://`` and ``user://``). + +:: + + # Standard + var dir = DirAccess.open("user://levels") + dir.make_dir("world1") + # Static + DirAccess.make_dir_absolute("user://levels/world1") + +\ **Note:** Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. Use :ref:`ResourceLoader` to access imported resources. + +Here is an example on how to iterate through the files of a directory: + + +.. tabs:: + + .. code-tab:: gdscript + + func dir_contents(path): + var dir = DirAccess.open(path) + if dir: + dir.list_dir_begin() + var file_name = dir.get_next() + while file_name != "": + if dir.current_is_dir(): + print("Found directory: " + file_name) + else: + print("Found file: " + file_name) + file_name = dir.get_next() + else: + print("An error occurred when trying to access the path.") + + .. code-tab:: csharp + + public void DirContents(string path) + { + using var dir = DirAccess.Open(path); + if (dir != null) + { + dir.ListDirBegin(); + string fileName = dir.GetNext(); + while (fileName != "") + { + if (dir.CurrentIsDir()) + { + GD.Print("Found directory: " + fileName); + } + else + { + GD.Print("Found file: " + fileName); + } + fileName = dir.GetNext(); + } + } + else + { + GD.Print("An error occurred when trying to access the path."); + } + } + + + +Tutorials +--------- + +- :doc:`File system <../tutorials/scripting/filesystem>` + +Properties +---------- + ++-------------------------+----------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`include_hidden` | ++-------------------------+----------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`include_navigational` | ++-------------------------+----------------------------------------------------------------------------+ + +Methods +------- + ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`change_dir` **(** :ref:`String` to_dir **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`copy` **(** :ref:`String` from, :ref:`String` to, :ref:`int` chmod_flags=-1 **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`copy_absolute` **(** :ref:`String` from, :ref:`String` to, :ref:`int` chmod_flags=-1 **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`current_is_dir` **(** **)** |const| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`dir_exists` **(** :ref:`String` path **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`dir_exists_absolute` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`file_exists` **(** :ref:`String` path **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_current_dir` **(** :ref:`bool` include_drive=true **)** |const| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_current_drive` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedStringArray` | :ref:`get_directories` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedStringArray` | :ref:`get_directories_at` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_drive_count` **(** **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_drive_name` **(** :ref:`int` idx **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedStringArray` | :ref:`get_files` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedStringArray` | :ref:`get_files_at` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_next` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`get_open_error` **(** **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_space_left` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`list_dir_begin` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`list_dir_end` **(** **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`make_dir` **(** :ref:`String` path **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`make_dir_absolute` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`make_dir_recursive` **(** :ref:`String` path **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`make_dir_recursive_absolute` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`DirAccess` | :ref:`open` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`remove` **(** :ref:`String` path **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`remove_absolute` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`rename` **(** :ref:`String` from, :ref:`String` to **)** | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`rename_absolute` **(** :ref:`String` from, :ref:`String` to **)** |static| | ++---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Property Descriptions +--------------------- + +.. _class_DirAccess_property_include_hidden: + +- :ref:`bool` **include_hidden** + ++----------+---------------------------+ +| *Setter* | set_include_hidden(value) | ++----------+---------------------------+ +| *Getter* | get_include_hidden() | ++----------+---------------------------+ + +If ``true``, hidden files are included when the navigating directory. + +Affects :ref:`list_dir_begin`, :ref:`get_directories` and :ref:`get_files`. + +---- + +.. _class_DirAccess_property_include_navigational: + +- :ref:`bool` **include_navigational** + ++----------+---------------------------------+ +| *Setter* | set_include_navigational(value) | ++----------+---------------------------------+ +| *Getter* | get_include_navigational() | ++----------+---------------------------------+ + +If ``true``, ``.`` and ``..`` are included when navigating the directory. + +Affects :ref:`list_dir_begin` and :ref:`get_directories`. + +Method Descriptions +------------------- + +.. _class_DirAccess_method_change_dir: + +- :ref:`Error` **change_dir** **(** :ref:`String` to_dir **)** + +Changes the currently opened directory to the one passed as an argument. The argument can be relative to the current directory (e.g. ``newdir`` or ``../newdir``), or an absolute path (e.g. ``/tmp/newdir`` or ``res://somedir/newdir``). + +Returns one of the :ref:`Error` code constants (``OK`` on success). + +---- + +.. _class_DirAccess_method_copy: + +- :ref:`Error` **copy** **(** :ref:`String` from, :ref:`String` to, :ref:`int` chmod_flags=-1 **)** + +Copies the ``from`` file to the ``to`` destination. Both arguments should be paths to files, either relative or absolute. If the destination file exists and is not access-protected, it will be overwritten. + +If ``chmod_flags`` is different than ``-1``, the Unix permissions for the destination path will be set to the provided value, if available on the current operating system. + +Returns one of the :ref:`Error` code constants (``OK`` on success). + +---- + +.. _class_DirAccess_method_copy_absolute: + +- :ref:`Error` **copy_absolute** **(** :ref:`String` from, :ref:`String` to, :ref:`int` chmod_flags=-1 **)** |static| + +Static version of :ref:`copy`. Supports only absolute paths. + +---- + +.. _class_DirAccess_method_current_is_dir: + +- :ref:`bool` **current_is_dir** **(** **)** |const| + +Returns whether the current item processed with the last :ref:`get_next` call is a directory (``.`` and ``..`` are considered directories). + +---- + +.. _class_DirAccess_method_dir_exists: + +- :ref:`bool` **dir_exists** **(** :ref:`String` path **)** + +Returns whether the target directory exists. The argument can be relative to the current directory, or an absolute path. + +---- + +.. _class_DirAccess_method_dir_exists_absolute: + +- :ref:`bool` **dir_exists_absolute** **(** :ref:`String` path **)** |static| + +Static version of :ref:`dir_exists`. Supports only absolute paths. + +---- + +.. _class_DirAccess_method_file_exists: + +- :ref:`bool` **file_exists** **(** :ref:`String` path **)** + +Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path. + +For a static equivalent, use :ref:`FileAccess.file_exists`. + +---- + +.. _class_DirAccess_method_get_current_dir: + +- :ref:`String` **get_current_dir** **(** :ref:`bool` include_drive=true **)** |const| + +Returns the absolute path to the currently opened directory (e.g. ``res://folder`` or ``C:\tmp\folder``). + +---- + +.. _class_DirAccess_method_get_current_drive: + +- :ref:`int` **get_current_drive** **(** **)** + +Returns the currently opened directory's drive index. See :ref:`get_drive_name` to convert returned index to the name of the drive. + +---- + +.. _class_DirAccess_method_get_directories: + +- :ref:`PackedStringArray` **get_directories** **(** **)** + +Returns a :ref:`PackedStringArray` containing filenames of the directory contents, excluding files. The array is sorted alphabetically. + +Affected by :ref:`include_hidden` and :ref:`include_navigational`. + +---- + +.. _class_DirAccess_method_get_directories_at: + +- :ref:`PackedStringArray` **get_directories_at** **(** :ref:`String` path **)** |static| + +Returns a :ref:`PackedStringArray` containing filenames of the directory contents, excluding files, at the given ``path``. The array is sorted alphabetically. + +Use :ref:`get_directories` if you want more control of what gets included. + +---- + +.. _class_DirAccess_method_get_drive_count: + +- :ref:`int` **get_drive_count** **(** **)** |static| + +On Windows, returns the number of drives (partitions) mounted on the current filesystem. + +On macOS, returns the number of mounted volumes. + +On Linux, returns the number of mounted volumes and GTK 3 bookmarks. + +On other platforms, the method returns 0. + +---- + +.. _class_DirAccess_method_get_drive_name: + +- :ref:`String` **get_drive_name** **(** :ref:`int` idx **)** |static| + +On Windows, returns the name of the drive (partition) passed as an argument (e.g. ``C:``). + +On macOS, returns the path to the mounted volume passed as an argument. + +On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument. + +On other platforms, or if the requested drive does not exist, the method returns an empty String. + +---- + +.. _class_DirAccess_method_get_files: + +- :ref:`PackedStringArray` **get_files** **(** **)** + +Returns a :ref:`PackedStringArray` containing filenames of the directory contents, excluding directories. The array is sorted alphabetically. + +Affected by :ref:`include_hidden`. + +---- + +.. _class_DirAccess_method_get_files_at: + +- :ref:`PackedStringArray` **get_files_at** **(** :ref:`String` path **)** |static| + +Returns a :ref:`PackedStringArray` containing filenames of the directory contents, excluding directories, at the given ``path``. The array is sorted alphabetically. + +Use :ref:`get_files` if you want more control of what gets included. + +---- + +.. _class_DirAccess_method_get_next: + +- :ref:`String` **get_next** **(** **)** + +Returns the next element (file or directory) in the current directory. + +The name of the file or directory is returned (and not its full path). Once the stream has been fully processed, the method returns an empty :ref:`String` and closes the stream automatically (i.e. :ref:`list_dir_end` would not be mandatory in such a case). + +---- + +.. _class_DirAccess_method_get_open_error: + +- :ref:`Error` **get_open_error** **(** **)** |static| + +Returns the result of the last :ref:`open` call in the current thread. + +---- + +.. _class_DirAccess_method_get_space_left: + +- :ref:`int` **get_space_left** **(** **)** + +Returns the available space on the current directory's disk, in bytes. Returns ``0`` if the platform-specific method to query the available space fails. + +---- + +.. _class_DirAccess_method_list_dir_begin: + +- :ref:`Error` **list_dir_begin** **(** **)** + +Initializes the stream used to list all files and directories using the :ref:`get_next` function, closing the currently opened stream if needed. Once the stream has been processed, it should typically be closed with :ref:`list_dir_end`. + +Affected by :ref:`include_hidden` and :ref:`include_navigational`. + +\ **Note:** The order of files and directories returned by this method is not deterministic, and can vary between operating systems. If you want a list of all files or folders sorted alphabetically, use :ref:`get_files` or :ref:`get_directories`. + +---- + +.. _class_DirAccess_method_list_dir_end: + +- void **list_dir_end** **(** **)** + +Closes the current stream opened with :ref:`list_dir_begin` (whether it has been fully processed with :ref:`get_next` does not matter). + +---- + +.. _class_DirAccess_method_make_dir: + +- :ref:`Error` **make_dir** **(** :ref:`String` path **)** + +Creates a directory. The argument can be relative to the current directory, or an absolute path. The target directory should be placed in an already existing directory (to create the full path recursively, see :ref:`make_dir_recursive`). + +Returns one of the :ref:`Error` code constants (``OK`` on success). + +---- + +.. _class_DirAccess_method_make_dir_absolute: + +- :ref:`Error` **make_dir_absolute** **(** :ref:`String` path **)** |static| + +Static version of :ref:`make_dir`. Supports only absolute paths. + +---- + +.. _class_DirAccess_method_make_dir_recursive: + +- :ref:`Error` **make_dir_recursive** **(** :ref:`String` path **)** + +Creates a target directory and all necessary intermediate directories in its path, by calling :ref:`make_dir` recursively. The argument can be relative to the current directory, or an absolute path. + +Returns one of the :ref:`Error` code constants (``OK`` on success). + +---- + +.. _class_DirAccess_method_make_dir_recursive_absolute: + +- :ref:`Error` **make_dir_recursive_absolute** **(** :ref:`String` path **)** |static| + +Static version of :ref:`make_dir_recursive`. Supports only absolute paths. + +---- + +.. _class_DirAccess_method_open: + +- :ref:`DirAccess` **open** **(** :ref:`String` path **)** |static| + +Creates a new ``DirAccess`` object and opens an existing directory of the filesystem. The ``path`` argument can be within the project tree (``res://folder``), the user directory (``user://folder``) or an absolute path of the user filesystem (e.g. ``/tmp/folder`` or ``C:\tmp\folder``). + +Returns ``null`` if opening the directory failed. You can use :ref:`get_open_error` to check the error that occurred. + +---- + +.. _class_DirAccess_method_remove: + +- :ref:`Error` **remove** **(** :ref:`String` path **)** + +Permanently deletes the target file or an empty directory. The argument can be relative to the current directory, or an absolute path. If the target directory is not empty, the operation will fail. + +If you don't want to delete the file/directory permanently, use :ref:`OS.move_to_trash` instead. + +Returns one of the :ref:`Error` code constants (``OK`` on success). + +---- + +.. _class_DirAccess_method_remove_absolute: + +- :ref:`Error` **remove_absolute** **(** :ref:`String` path **)** |static| + +Static version of :ref:`remove`. Supports only absolute paths. + +---- + +.. _class_DirAccess_method_rename: + +- :ref:`Error` **rename** **(** :ref:`String` from, :ref:`String` to **)** + +Renames (move) the ``from`` file or directory to the ``to`` destination. Both arguments should be paths to files or directories, either relative or absolute. If the destination file or directory exists and is not access-protected, it will be overwritten. + +Returns one of the :ref:`Error` code constants (``OK`` on success). + +---- + +.. _class_DirAccess_method_rename_absolute: + +- :ref:`Error` **rename_absolute** **(** :ref:`String` from, :ref:`String` to **)** |static| + +Static version of :ref:`rename`. Supports only absolute paths. + +.. |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.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` diff --git a/classes/class_directory.rst b/classes/class_directory.rst deleted file mode 100644 index cf1df29b9..000000000 --- a/classes/class_directory.rst +++ /dev/null @@ -1,381 +0,0 @@ -:github_url: hide - -.. DO NOT EDIT THIS FILE!!! -.. Generated automatically from Godot engine sources. -.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. -.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/Directory.xml. - -.. _class_Directory: - -Directory -========= - -**Inherits:** :ref:`RefCounted` **<** :ref:`Object` - -Type used to handle the filesystem. - -Description ------------ - -Directory type. It is used to manage directories and their content (not restricted to the project folder). - -When creating a new ``Directory``, it must be explicitly opened using :ref:`open` before most methods can be used. However, :ref:`file_exists` and :ref:`dir_exists` can be used without opening a directory. If so, they use a path relative to ``res://``. - -\ **Note:** Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. Use :ref:`ResourceLoader` to access imported resources. - -Here is an example on how to iterate through the files of a directory: - - -.. tabs:: - - .. code-tab:: gdscript - - func dir_contents(path): - var dir = Directory.new() - if dir.open(path) == OK: - dir.list_dir_begin() - var file_name = dir.get_next() - while file_name != "": - if dir.current_is_dir(): - print("Found directory: " + file_name) - else: - print("Found file: " + file_name) - file_name = dir.get_next() - else: - print("An error occurred when trying to access the path.") - - .. code-tab:: csharp - - public void DirContents(string path) - { - var dir = new Directory(); - if (dir.Open(path) == Error.Ok) - { - dir.ListDirBegin(); - string fileName = dir.GetNext(); - while (fileName != "") - { - if (dir.CurrentIsDir()) - { - GD.Print("Found directory: " + fileName); - } - else - { - GD.Print("Found file: " + fileName); - } - fileName = dir.GetNext(); - } - } - else - { - GD.Print("An error occurred when trying to access the path."); - } - } - - - -Tutorials ---------- - -- :doc:`File system <../tutorials/scripting/filesystem>` - -Properties ----------- - -+-------------------------+----------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`include_hidden` | ``false`` | -+-------------------------+----------------------------------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`include_navigational` | ``false`` | -+-------------------------+----------------------------------------------------------------------------+-----------+ - -Methods -------- - -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`change_dir` **(** :ref:`String` todir **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`copy` **(** :ref:`String` from, :ref:`String` to **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`current_is_dir` **(** **)** |const| | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`dir_exists` **(** :ref:`String` path **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`file_exists` **(** :ref:`String` path **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_current_dir` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_current_drive` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_directories` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_drive` **(** :ref:`int` idx **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_drive_count` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_files` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_next` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_space_left` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`list_dir_begin` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`list_dir_end` **(** **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`make_dir` **(** :ref:`String` path **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`make_dir_recursive` **(** :ref:`String` path **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`open` **(** :ref:`String` path **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`remove` **(** :ref:`String` path **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`rename` **(** :ref:`String` from, :ref:`String` to **)** | -+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+ - -Property Descriptions ---------------------- - -.. _class_Directory_property_include_hidden: - -- :ref:`bool` **include_hidden** - -+-----------+---------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------+ -| *Setter* | set_include_hidden(value) | -+-----------+---------------------------+ -| *Getter* | get_include_hidden() | -+-----------+---------------------------+ - -If ``true``, hidden files are included when the navigating directory. - -Affects :ref:`list_dir_begin`, :ref:`get_directories` and :ref:`get_files`. - ----- - -.. _class_Directory_property_include_navigational: - -- :ref:`bool` **include_navigational** - -+-----------+---------------------------------+ -| *Default* | ``false`` | -+-----------+---------------------------------+ -| *Setter* | set_include_navigational(value) | -+-----------+---------------------------------+ -| *Getter* | get_include_navigational() | -+-----------+---------------------------------+ - -If ``true``, ``.`` and ``..`` are included when navigating the directory. - -Affects :ref:`list_dir_begin` and :ref:`get_directories`. - -Method Descriptions -------------------- - -.. _class_Directory_method_change_dir: - -- :ref:`Error` **change_dir** **(** :ref:`String` todir **)** - -Changes the currently opened directory to the one passed as an argument. The argument can be relative to the current directory (e.g. ``newdir`` or ``../newdir``), or an absolute path (e.g. ``/tmp/newdir`` or ``res://somedir/newdir``). - -Returns one of the :ref:`Error` code constants (``OK`` on success). - ----- - -.. _class_Directory_method_copy: - -- :ref:`Error` **copy** **(** :ref:`String` from, :ref:`String` to **)** - -Copies the ``from`` file to the ``to`` destination. Both arguments should be paths to files, either relative or absolute. If the destination file exists and is not access-protected, it will be overwritten. - -Returns one of the :ref:`Error` code constants (``OK`` on success). - ----- - -.. _class_Directory_method_current_is_dir: - -- :ref:`bool` **current_is_dir** **(** **)** |const| - -Returns whether the current item processed with the last :ref:`get_next` call is a directory (``.`` and ``..`` are considered directories). - ----- - -.. _class_Directory_method_dir_exists: - -- :ref:`bool` **dir_exists** **(** :ref:`String` path **)** - -Returns whether the target directory exists. The argument can be relative to the current directory, or an absolute path. - -If the ``Directory`` is not open, the path is relative to ``res://``. - ----- - -.. _class_Directory_method_file_exists: - -- :ref:`bool` **file_exists** **(** :ref:`String` path **)** - -Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path. - -If the ``Directory`` is not open, the path is relative to ``res://``. - ----- - -.. _class_Directory_method_get_current_dir: - -- :ref:`String` **get_current_dir** **(** **)** - -Returns the absolute path to the currently opened directory (e.g. ``res://folder`` or ``C:\tmp\folder``). - ----- - -.. _class_Directory_method_get_current_drive: - -- :ref:`int` **get_current_drive** **(** **)** - -Returns the currently opened directory's drive index. See :ref:`get_drive` to convert returned index to the name of the drive. - ----- - -.. _class_Directory_method_get_directories: - -- :ref:`PackedStringArray` **get_directories** **(** **)** - -Returns a :ref:`PackedStringArray` containing filenames of the directory contents, excluding files. The array is sorted alphabetically. - -Affected by :ref:`include_hidden` and :ref:`include_navigational`. - ----- - -.. _class_Directory_method_get_drive: - -- :ref:`String` **get_drive** **(** :ref:`int` idx **)** - -On Windows, returns the name of the drive (partition) passed as an argument (e.g. ``C:``). - -On macOS, returns the path to the mounted volume passed as an argument. - -On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument. - -On other platforms, or if the requested drive does not exist, the method returns an empty String. - ----- - -.. _class_Directory_method_get_drive_count: - -- :ref:`int` **get_drive_count** **(** **)** - -On Windows, returns the number of drives (partitions) mounted on the current filesystem. - -On macOS, returns the number of mounted volumes. - -On Linux, returns the number of mounted volumes and GTK 3 bookmarks. - -On other platforms, the method returns 0. - ----- - -.. _class_Directory_method_get_files: - -- :ref:`PackedStringArray` **get_files** **(** **)** - -Returns a :ref:`PackedStringArray` containing filenames of the directory contents, excluding directories. The array is sorted alphabetically. - -Affected by :ref:`include_hidden`. - ----- - -.. _class_Directory_method_get_next: - -- :ref:`String` **get_next** **(** **)** - -Returns the next element (file or directory) in the current directory (including ``.`` and ``..``, unless ``skip_navigational`` was given to :ref:`list_dir_begin`). - -The name of the file or directory is returned (and not its full path). Once the stream has been fully processed, the method returns an empty String and closes the stream automatically (i.e. :ref:`list_dir_end` would not be mandatory in such a case). - ----- - -.. _class_Directory_method_get_space_left: - -- :ref:`int` **get_space_left** **(** **)** - -On UNIX desktop systems, returns the available space on the current directory's disk. On other platforms, this information is not available and the method returns 0 or -1. - ----- - -.. _class_Directory_method_list_dir_begin: - -- :ref:`Error` **list_dir_begin** **(** **)** - -Initializes the stream used to list all files and directories using the :ref:`get_next` function, closing the currently opened stream if needed. Once the stream has been processed, it should typically be closed with :ref:`list_dir_end`. - -Affected by :ref:`include_hidden` and :ref:`include_navigational`. - -\ **Note:** The order of files and directories returned by this method is not deterministic, and can vary between operating systems. If you want a list of all files or folders sorted alphabetically, use :ref:`get_files` or :ref:`get_directories`. - ----- - -.. _class_Directory_method_list_dir_end: - -- void **list_dir_end** **(** **)** - -Closes the current stream opened with :ref:`list_dir_begin` (whether it has been fully processed with :ref:`get_next` does not matter). - ----- - -.. _class_Directory_method_make_dir: - -- :ref:`Error` **make_dir** **(** :ref:`String` path **)** - -Creates a directory. The argument can be relative to the current directory, or an absolute path. The target directory should be placed in an already existing directory (to create the full path recursively, see :ref:`make_dir_recursive`). - -Returns one of the :ref:`Error` code constants (``OK`` on success). - ----- - -.. _class_Directory_method_make_dir_recursive: - -- :ref:`Error` **make_dir_recursive** **(** :ref:`String` path **)** - -Creates a target directory and all necessary intermediate directories in its path, by calling :ref:`make_dir` recursively. The argument can be relative to the current directory, or an absolute path. - -Returns one of the :ref:`Error` code constants (``OK`` on success). - ----- - -.. _class_Directory_method_open: - -- :ref:`Error` **open** **(** :ref:`String` path **)** - -Opens an existing directory of the filesystem. The ``path`` argument can be within the project tree (``res://folder``), the user directory (``user://folder``) or an absolute path of the user filesystem (e.g. ``/tmp/folder`` or ``C:\tmp\folder``). - -Returns one of the :ref:`Error` code constants (``OK`` on success). - ----- - -.. _class_Directory_method_remove: - -- :ref:`Error` **remove** **(** :ref:`String` path **)** - -Permanently deletes the target file or an empty directory. The argument can be relative to the current directory, or an absolute path. If the target directory is not empty, the operation will fail. - -If you don't want to delete the file/directory permanently, use :ref:`OS.move_to_trash` instead. - -Returns one of the :ref:`Error` code constants (``OK`` on success). - ----- - -.. _class_Directory_method_rename: - -- :ref:`Error` **rename** **(** :ref:`String` from, :ref:`String` to **)** - -Renames (move) the ``from`` file or directory to the ``to`` destination. Both arguments should be paths to files or directories, either relative or absolute. If the destination file or directory exists and is not access-protected, it will be overwritten. - -Returns one of the :ref:`Error` code constants (``OK`` on success). - -.. |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.)` -.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` -.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` -.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` diff --git a/classes/class_displayserver.rst b/classes/class_displayserver.rst index 6dd007d3c..d0912f6ac 100644 --- a/classes/class_displayserver.rst +++ b/classes/class_displayserver.rst @@ -320,6 +320,8 @@ Methods +----------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`window_set_vsync_mode` **(** :ref:`VSyncMode` vsync_mode, :ref:`int` window_id=0 **)** | +----------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`window_set_window_buttons_offset` **(** :ref:`Vector2i` offset, :ref:`int` window_id=0 **)** | ++----------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`window_set_window_event_callback` **(** :ref:`Callable` callback, :ref:`int` window_id=0 **)** | +----------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -606,21 +608,21 @@ enum **CursorShape**: enum **WindowMode**: -- **WINDOW_MODE_WINDOWED** = **0** +- **WINDOW_MODE_WINDOWED** = **0** --- Windowed mode, i.e. :ref:`Window` doesn't occupy the whole screen (unless set to the size of the screen). -- **WINDOW_MODE_MINIMIZED** = **1** +- **WINDOW_MODE_MINIMIZED** = **1** --- Minimized window mode, i.e. :ref:`Window` is not visible and available on window manager's window list. Normally happens when the minimize button is pressed. -- **WINDOW_MODE_MAXIMIZED** = **2** +- **WINDOW_MODE_MAXIMIZED** = **2** --- Maximized window mode, i.e. :ref:`Window` will occupy whole screen area except task bar and still display its borders. Normally happens when the minimize button is pressed. -- **WINDOW_MODE_FULLSCREEN** = **3** --- Fullscreen window mode. Note that this is not *exclusive* fullscreen. On Windows and Linux, a borderless window is used to emulate fullscreen. On macOS, a new desktop is used to display the running project. +- **WINDOW_MODE_FULLSCREEN** = **3** --- Full screen window mode. Note that this is not *exclusive* full screen. On Windows and Linux, a borderless window is used to emulate full screen. On macOS, a new desktop is used to display the running project. -Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports :doc:`multiple resolutions <../tutorials/rendering/multiple_resolutions>` when enabling fullscreen mode. +Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports :doc:`multiple resolutions <../tutorials/rendering/multiple_resolutions>` when enabling full screen mode. -- **WINDOW_MODE_EXCLUSIVE_FULLSCREEN** = **4** --- Exclusive fullscreen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to :ref:`WINDOW_MODE_FULLSCREEN`. +- **WINDOW_MODE_EXCLUSIVE_FULLSCREEN** = **4** --- Exclusive full screen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to :ref:`WINDOW_MODE_FULLSCREEN`. -Only one window in exclusive fullscreen mode can be visible on a given screen at a time. If multiple windows are in exclusive fullscreen mode for the same screen, the last one being set to this mode takes precedence. +Only one window in exclusive full screen mode can be visible on a given screen at a time. If multiple windows are in exclusive full screen mode for the same screen, the last one being set to this mode takes precedence. -Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports :doc:`multiple resolutions <../tutorials/rendering/multiple_resolutions>` when enabling fullscreen mode. +Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports :doc:`multiple resolutions <../tutorials/rendering/multiple_resolutions>` when enabling full screen mode. ---- @@ -644,23 +646,31 @@ Regardless of the platform, enabling fullscreen will change the window size to m enum **WindowFlags**: -- **WINDOW_FLAG_RESIZE_DISABLED** = **0** --- Window can't be resizing by dragging its resize grip. It's still possible to resize the window using :ref:`window_set_size`. This flag is ignored for full screen windows. +- **WINDOW_FLAG_RESIZE_DISABLED** = **0** --- The window can't be resizing by dragging its resize grip. It's still possible to resize the window using :ref:`window_set_size`. This flag is ignored for full screen windows. -- **WINDOW_FLAG_BORDERLESS** = **1** --- Window do not have native title bar and other decorations. This flag is ignored for full-screen windows. +- **WINDOW_FLAG_BORDERLESS** = **1** --- The window do not have native title bar and other decorations. This flag is ignored for full-screen windows. -- **WINDOW_FLAG_ALWAYS_ON_TOP** = **2** --- Window is floating above other regular windows. This flag is ignored for full-screen windows. +- **WINDOW_FLAG_ALWAYS_ON_TOP** = **2** --- The window is floating on top of all other windows. This flag is ignored for full-screen windows. -- **WINDOW_FLAG_TRANSPARENT** = **3** --- Window is will be destroyed with its transient parent and displayed on top of non-exclusive full-screen parent window. Transient windows can't enter full-screen mode. +- **WINDOW_FLAG_TRANSPARENT** = **3** --- The window background can be transparent. -- **WINDOW_FLAG_NO_FOCUS** = **4** --- Window can't be focused. No-focus window will ignore all input, except mouse clicks. +\ **Note:** This flag has no effect if :ref:`ProjectSettings.display/window/per_pixel_transparency/allowed` is set to ``false``. -- **WINDOW_FLAG_POPUP** = **5** --- Window is part of menu or :ref:`OptionButton` dropdown. This flag can't be changed when window is visible. An active popup window will exclusively receive all input, without stealing focus from its parent. Popup windows are automatically closed when uses click outside it, or when an application is switched. Popup window must have :ref:`WINDOW_FLAG_TRANSPARENT` set. +\ **Note:** Transparency support is implemented on Linux, macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. + +- **WINDOW_FLAG_NO_FOCUS** = **4** --- The window can't be focused. No-focus window will ignore all input, except mouse clicks. + +- **WINDOW_FLAG_POPUP** = **5** --- Window is part of menu or :ref:`OptionButton` dropdown. This flag can't be changed when the window is visible. An active popup window will exclusively receive all input, without stealing focus from its parent. Popup windows are automatically closed when uses click outside it, or when an application is switched. Popup window must have ``transient parent`` set (see :ref:`window_set_transient`). - **WINDOW_FLAG_EXTEND_TO_TITLE** = **6** --- Window content is expanded to the full size of the window. Unlike borderless window, the frame is left intact and can be used to resize the window, title bar is transparent, but have minimize/maximize/close buttons. +Use :ref:`window_set_window_buttons_offset` to adjust minimize/maximize/close buttons offset. + +Use :ref:`window_get_safe_title_margins` to determine area under the title bar that is not covered by decorations. + \ **Note:** This flag is implemented on macOS. -- **WINDOW_FLAG_MAX** = **7** +- **WINDOW_FLAG_MAX** = **7** --- Max value of the :ref:`WindowFlags`. ---- @@ -680,21 +690,31 @@ enum **WindowFlags**: .. _class_DisplayServer_constant_WINDOW_EVENT_DPI_CHANGE: +.. _class_DisplayServer_constant_WINDOW_EVENT_TITLEBAR_CHANGE: + enum **WindowEvent**: -- **WINDOW_EVENT_MOUSE_ENTER** = **0** +- **WINDOW_EVENT_MOUSE_ENTER** = **0** --- Sent when the mouse pointer enters the window, see :ref:`window_set_window_event_callback`. -- **WINDOW_EVENT_MOUSE_EXIT** = **1** +- **WINDOW_EVENT_MOUSE_EXIT** = **1** --- Sent when the mouse pointer exits the window, see :ref:`window_set_window_event_callback`. -- **WINDOW_EVENT_FOCUS_IN** = **2** +- **WINDOW_EVENT_FOCUS_IN** = **2** --- Sent when the window grabs focus, see :ref:`window_set_window_event_callback`. -- **WINDOW_EVENT_FOCUS_OUT** = **3** +- **WINDOW_EVENT_FOCUS_OUT** = **3** --- Sent when the window loses focus, see :ref:`window_set_window_event_callback`. -- **WINDOW_EVENT_CLOSE_REQUEST** = **4** +- **WINDOW_EVENT_CLOSE_REQUEST** = **4** --- Sent when the user has attempted to close the window (e.g. close button is pressed), see :ref:`window_set_window_event_callback`. -- **WINDOW_EVENT_GO_BACK_REQUEST** = **5** +- **WINDOW_EVENT_GO_BACK_REQUEST** = **5** --- Sent when the device "Back" button is pressed, see :ref:`window_set_window_event_callback`. -- **WINDOW_EVENT_DPI_CHANGE** = **6** +\ **Note:** This event is implemented on Android. + +- **WINDOW_EVENT_DPI_CHANGE** = **6** --- Sent when the window is moved to the display with different DPI, or display DPI is changed, see :ref:`window_set_window_event_callback`. + +\ **Note:** This flag is implemented on macOS. + +- **WINDOW_EVENT_TITLEBAR_CHANGE** = **7** --- Sent when the window title bar decoration is changed (e.g. :ref:`WINDOW_FLAG_EXTEND_TO_TITLE` is set or window entered/exited full screen mode), see :ref:`window_set_window_event_callback`. + +\ **Note:** This flag is implemented on macOS. ---- @@ -2169,7 +2189,7 @@ Sets the minimum size for the given window to ``min_size`` (in pixels). Sets window mode for the given window to ``mode``. See :ref:`WindowMode` for possible values and how each mode behaves. -\ **Note:** Setting the window to fullscreen forcibly sets the borderless flag to ``true``, so make sure to set it back to ``false`` when not wanted. +\ **Note:** Setting the window to full screen forcibly sets the borderless flag to ``true``, so make sure to set it back to ``false`` when not wanted. ---- @@ -2256,6 +2276,10 @@ Sets the title of the given window to ``title``. - void **window_set_transient** **(** :ref:`int` window_id, :ref:`int` parent_window_id **)** +Sets window transient parent. Transient window is will be destroyed with its transient parent and will return focus to their parent when closed. The transient window is displayed on top of a non-exclusive full-screen parent window. Transient windows can't enter full-screen mode. + +Note that behavior might be different depending on the platform. + ---- .. _class_DisplayServer_method_window_set_vsync_mode: @@ -2270,6 +2294,16 @@ Depending on the platform and used renderer, the engine will fall back to :ref:` ---- +.. _class_DisplayServer_method_window_set_window_buttons_offset: + +- void **window_set_window_buttons_offset** **(** :ref:`Vector2i` offset, :ref:`int` window_id=0 **)** + +When :ref:`WINDOW_FLAG_EXTEND_TO_TITLE` flag is set, set offset to the center of the first titlebar button. + +\ **Note:** This flag is implemented on macOS. + +---- + .. _class_DisplayServer_method_window_set_window_event_callback: - void **window_set_window_event_callback** **(** :ref:`Callable` callback, :ref:`int` window_id=0 **)** diff --git a/classes/class_editorimportplugin.rst b/classes/class_editorimportplugin.rst index fb6518a3c..041217277 100644 --- a/classes/class_editorimportplugin.rst +++ b/classes/class_editorimportplugin.rst @@ -28,7 +28,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr .. code-tab:: gdscript - tool + @tool extends EditorImportPlugin func _get_importer_name(): @@ -63,7 +63,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr # Fill the Mesh with data read in "file", left as an exercise to the reader. var filename = save_path + "." + _get_save_extension() - return ResourceSaver.save(filename, mesh) + return ResourceSaver.save(mesh, filename) .. code-tab:: csharp @@ -123,7 +123,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr var mesh = new ArrayMesh(); // Fill the Mesh with data read in "file", left as an exercise to the reader. String filename = savePath + "." + GetSaveExtension(); - return (int)ResourceSaver.Save(filename, mesh); + return (int)ResourceSaver.Save(mesh, filename); } } diff --git a/classes/class_editorinspector.rst b/classes/class_editorinspector.rst index ad1c94aea..bc908020e 100644 --- a/classes/class_editorinspector.rst +++ b/classes/class_editorinspector.rst @@ -36,6 +36,13 @@ Properties | :ref:`ScrollMode` | horizontal_scroll_mode | ``0`` (overrides :ref:`ScrollContainer`) | +----------------------------------------------------+------------------------+-------------------------------------------------------------------------------------------------+ +Methods +------- + ++-----------------------------+----------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_selected_path` **(** **)** |const| | ++-----------------------------+----------------------------------------------------------------------------------------------+ + Signals ------- @@ -111,6 +118,15 @@ Emitted when a resource is selected in the inspector. Emitted when a property that requires a restart to be applied is edited in the inspector. This is only used in the Project Settings and Editor Settings. +Method Descriptions +------------------- + +.. _class_EditorInspector_method_get_selected_path: + +- :ref:`String` **get_selected_path** **(** **)** |const| + +Gets the path of the currently selected property. + .. |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_editornode3dgizmo.rst b/classes/class_editornode3dgizmo.rst index ef6d267b7..efc4be52c 100644 --- a/classes/class_editornode3dgizmo.rst +++ b/classes/class_editornode3dgizmo.rst @@ -59,9 +59,9 @@ Methods +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear` **(** **)** | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`EditorNode3DGizmoPlugin` | :ref:`get_plugin` **(** **)** |const| | +| :ref:`Node3D` | :ref:`get_node_3d` **(** **)** |const| | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Node3D` | :ref:`get_spatial_node` **(** **)** |const| | +| :ref:`EditorNode3DGizmoPlugin` | :ref:`get_plugin` **(** **)** |const| | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedInt32Array` | :ref:`get_subgizmo_selection` **(** **)** |const| | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -69,7 +69,7 @@ Methods +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_hidden` **(** :ref:`bool` hidden **)** | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`set_spatial_node` **(** :ref:`Node` node **)** | +| void | :ref:`set_node_3d` **(** :ref:`Node` node **)** | +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Method Descriptions @@ -237,6 +237,14 @@ Removes everything in the gizmo including meshes, collisions and handles. ---- +.. _class_EditorNode3DGizmo_method_get_node_3d: + +- :ref:`Node3D` **get_node_3d** **(** **)** |const| + +Returns the :ref:`Node3D` node associated with this gizmo. + +---- + .. _class_EditorNode3DGizmo_method_get_plugin: - :ref:`EditorNode3DGizmoPlugin` **get_plugin** **(** **)** |const| @@ -245,14 +253,6 @@ Returns the :ref:`EditorNode3DGizmoPlugin` that o ---- -.. _class_EditorNode3DGizmo_method_get_spatial_node: - -- :ref:`Node3D` **get_spatial_node** **(** **)** |const| - -Returns the Node3D node associated with this gizmo. - ----- - .. _class_EditorNode3DGizmo_method_get_subgizmo_selection: - :ref:`PackedInt32Array` **get_subgizmo_selection** **(** **)** |const| @@ -277,9 +277,9 @@ Sets the gizmo's hidden state. If ``true``, the gizmo will be hidden. If ``false ---- -.. _class_EditorNode3DGizmo_method_set_spatial_node: +.. _class_EditorNode3DGizmo_method_set_node_3d: -- void **set_spatial_node** **(** :ref:`Node` node **)** +- void **set_node_3d** **(** :ref:`Node` node **)** Sets the reference :ref:`Node3D` node for the gizmo. ``node`` must inherit from :ref:`Node3D`. diff --git a/classes/class_editornode3dgizmoplugin.rst b/classes/class_editornode3dgizmoplugin.rst index 38ea775fa..4288199fc 100644 --- a/classes/class_editornode3dgizmoplugin.rst +++ b/classes/class_editornode3dgizmoplugin.rst @@ -19,12 +19,12 @@ Description ``EditorNode3DGizmoPlugin`` allows you to define a new type of Gizmo. There are two main ways to do so: extending ``EditorNode3DGizmoPlugin`` for the simpler gizmos, or creating a new :ref:`EditorNode3DGizmo` type. See the tutorial in the documentation for more info. -To use ``EditorNode3DGizmoPlugin``, register it using the :ref:`EditorPlugin.add_spatial_gizmo_plugin` method first. +To use ``EditorNode3DGizmoPlugin``, register it using the :ref:`EditorPlugin.add_node_3d_gizmo_plugin` method first. Tutorials --------- -- :doc:`Spatial gizmo plugins <../tutorials/plugins/editor/spatial_gizmos>` +- :doc:`Node3D gizmo plugins <../tutorials/plugins/editor/spatial_gizmos>` Methods ------- diff --git a/classes/class_editorplugin.rst b/classes/class_editorplugin.rst index 1da800752..113ad80af 100644 --- a/classes/class_editorplugin.rst +++ b/classes/class_editorplugin.rst @@ -92,12 +92,12 @@ Methods +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_inspector_plugin` **(** :ref:`EditorInspectorPlugin` plugin **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`add_node_3d_gizmo_plugin` **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** | ++-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_scene_format_importer_plugin` **(** :ref:`EditorSceneFormatImporter` scene_format_importer, :ref:`bool` first_priority=false **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_scene_post_import_plugin` **(** :ref:`EditorScenePostImportPlugin` scene_import_plugin, :ref:`bool` first_priority=false **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`add_spatial_gizmo_plugin` **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** | -+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_tool_menu_item` **(** :ref:`String` name, :ref:`Callable` callable **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_tool_submenu_item` **(** :ref:`String` name, :ref:`PopupMenu` submenu **)** | @@ -138,12 +138,12 @@ Methods +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_inspector_plugin` **(** :ref:`EditorInspectorPlugin` plugin **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`remove_node_3d_gizmo_plugin` **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** | ++-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_scene_format_importer_plugin` **(** :ref:`EditorSceneFormatImporter` scene_format_importer **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_scene_post_import_plugin` **(** :ref:`EditorScenePostImportPlugin` scene_import_plugin **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`remove_spatial_gizmo_plugin` **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** | -+-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_tool_menu_item` **(** :ref:`String` name **)** | +-----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_translation_parser_plugin` **(** :ref:`EditorTranslationParserPlugin` parser **)** | @@ -600,7 +600,7 @@ Ideally, the plugin icon should be white with a transparent background and 16x16 # You can use a custom icon: return preload("res://addons/my_plugin/my_plugin_icon.svg") # Or use a built-in icon: - return get_editor_interface().get_base_control().get_icon("Node", "EditorIcons") + return get_editor_interface().get_base_control().get_theme_icon("Node", "EditorIcons") .. code-tab:: csharp @@ -609,7 +609,7 @@ Ideally, the plugin icon should be white with a transparent background and 16x16 // You can use a custom icon: return ResourceLoader.Load("res://addons/my_plugin/my_plugin_icon.svg"); // Or use a built-in icon: - return GetEditorInterface().GetBaseControl().GetIcon("Node", "EditorIcons"); + return GetEditorInterface().GetBaseControl().GetThemeIcon("Node", "EditorIcons"); } @@ -863,6 +863,16 @@ Registers a new :ref:`EditorInspectorPlugin`. Inspe +---- + +.. _class_EditorPlugin_method_add_node_3d_gizmo_plugin: + +- void **add_node_3d_gizmo_plugin** **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** + +Registers a new :ref:`EditorNode3DGizmoPlugin`. Gizmo plugins are used to add custom gizmos to the 3D preview viewport for a :ref:`Node3D`. + +See :ref:`add_inspector_plugin` for an example of how to register a plugin. + ---- .. _class_EditorPlugin_method_add_scene_format_importer_plugin: @@ -885,16 +895,6 @@ If ``first_priority`` is ``true``, the new import plugin is inserted first in th ---- -.. _class_EditorPlugin_method_add_spatial_gizmo_plugin: - -- void **add_spatial_gizmo_plugin** **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** - -Registers a new :ref:`EditorNode3DGizmoPlugin`. Gizmo plugins are used to add custom gizmos to the 3D preview viewport for a :ref:`Node3D`. - -See :ref:`add_inspector_plugin` for an example of how to register a plugin. - ----- - .. _class_EditorPlugin_method_add_tool_menu_item: - void **add_tool_menu_item** **(** :ref:`String` name, :ref:`Callable` callable **)** @@ -1061,6 +1061,14 @@ Removes an inspector plugin registered by :ref:`add_import_plugin` plugin **)** + +Removes a gizmo plugin registered by :ref:`add_node_3d_gizmo_plugin`. + +---- + .. _class_EditorPlugin_method_remove_scene_format_importer_plugin: - void **remove_scene_format_importer_plugin** **(** :ref:`EditorSceneFormatImporter` scene_format_importer **)** @@ -1077,14 +1085,6 @@ Remove the :ref:`EditorScenePostImportPlugin` ---- -.. _class_EditorPlugin_method_remove_spatial_gizmo_plugin: - -- void **remove_spatial_gizmo_plugin** **(** :ref:`EditorNode3DGizmoPlugin` plugin **)** - -Removes a gizmo plugin registered by :ref:`add_spatial_gizmo_plugin`. - ----- - .. _class_EditorPlugin_method_remove_tool_menu_item: - void **remove_tool_menu_item** **(** :ref:`String` name **)** diff --git a/classes/class_editorproperty.rst b/classes/class_editorproperty.rst index 7e5565504..44ee9fac6 100644 --- a/classes/class_editorproperty.rst +++ b/classes/class_editorproperty.rst @@ -41,6 +41,8 @@ Properties Methods ------- ++-------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`_set_read_only` **(** :ref:`bool` read_only **)** |virtual| | +-------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_update_property` **(** **)** |virtual| | +-------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -264,6 +266,14 @@ Used by the inspector, set to ``true`` when the property is read-only. Method Descriptions ------------------- +.. _class_EditorProperty_method__set_read_only: + +- void **_set_read_only** **(** :ref:`bool` read_only **)** |virtual| + +Called when the read-only status of the property is changed. It may be used to change custom controls into a read-only or modifiable state. + +---- + .. _class_EditorProperty_method__update_property: - void **_update_property** **(** **)** |virtual| diff --git a/classes/class_editorscenepostimport.rst b/classes/class_editorscenepostimport.rst index 541674e5f..c5a6d31b8 100644 --- a/classes/class_editorscenepostimport.rst +++ b/classes/class_editorscenepostimport.rst @@ -26,7 +26,7 @@ The :ref:`_post_import` callbac .. code-tab:: gdscript - tool # Needed so it runs in editor. + @tool # Needed so it runs in editor. extends EditorScenePostImport # This sample changes all node names. # Called right after the scene is imported and gets the root node. diff --git a/classes/class_editorscript.rst b/classes/class_editorscript.rst index f88a83459..2f14ade2d 100644 --- a/classes/class_editorscript.rst +++ b/classes/class_editorscript.rst @@ -28,7 +28,7 @@ Scripts extending this class and implementing its :ref:`_run`. @@ -1143,7 +1143,7 @@ If ``true``, allows panning by holding down :kbd:`Space` in the 2D editor viewpo - :ref:`int` **editors/panning/sub_editors_panning_scheme** -Controls whether the mouse wheel scroll zooms or pans in subeditors. The list of affected subeditors is: animation blend tree editor, :ref:`Polygon2D` editor, tileset editor, texture region editor, visual shader editor and visual script editor. See also :ref:`editors/panning/2d_editor_panning_scheme` and :ref:`editors/panning/animation_editors_panning_scheme`. +Controls whether the mouse wheel scroll zooms or pans in subeditors. The list of affected subeditors is: animation blend tree editor, :ref:`Polygon2D` editor, tileset editor, texture region editor and visual shader editor. See also :ref:`editors/panning/2d_editor_panning_scheme` and :ref:`editors/panning/animation_editors_panning_scheme`. ---- @@ -1193,7 +1193,7 @@ The color to use for the TileMap editor's grid. - :ref:`float` **editors/visual_editors/lines_curvature** -The curvature to use for connection lines in the visual script and visual shader editors. Higher values will make connection lines appear more curved, with values above ``0.5`` resulting in more "angular" turns in the middle of connection lines. +The curvature to use for connection lines in the visual shader editor. Higher values will make connection lines appear more curved, with values above ``0.5`` resulting in more "angular" turns in the middle of connection lines. ---- @@ -1201,7 +1201,7 @@ The curvature to use for connection lines in the visual script and visual shader - :ref:`float` **editors/visual_editors/minimap_opacity** -The opacity of the minimap displayed in the bottom-right corner of the visual script and visual shader editors. +The opacity of the minimap displayed in the bottom-right corner of the visual shader editor. ---- diff --git a/classes/class_editortranslationparserplugin.rst b/classes/class_editortranslationparserplugin.rst index 6592e80c5..9002104d6 100644 --- a/classes/class_editortranslationparserplugin.rst +++ b/classes/class_editortranslationparserplugin.rst @@ -32,7 +32,7 @@ Below shows an example of a custom parser that extracts strings from a CSV file .. code-tab:: gdscript - tool + @tool extends EditorTranslationParserPlugin func _parse_file(path, msgids, msgids_context_plural): @@ -101,7 +101,7 @@ To add a translatable string associated with context or plural, add it to ``msgi -\ **Note:** If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the ``path`` argument using :ref:`ResourceLoader.load`. This is because built-in scripts are loaded as :ref:`Resource` type, not :ref:`File` type. +\ **Note:** If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the ``path`` argument using :ref:`ResourceLoader.load`. This is because built-in scripts are loaded as :ref:`Resource` type, not :ref:`FileAccess` type. For example: diff --git a/classes/class_engine.rst b/classes/class_engine.rst index 159886089..95307acf5 100644 --- a/classes/class_engine.rst +++ b/classes/class_engine.rst @@ -22,6 +22,8 @@ The ``Engine`` singleton allows you to query and modify the project's run-time p Properties ---------- ++---------------------------+---------------------------------------------------------------------------------+----------+ +| :ref:`int` | :ref:`max_fps` | ``0`` | +---------------------------+---------------------------------------------------------------------------------+----------+ | :ref:`float` | :ref:`physics_jitter_fix` | ``0.5`` | +---------------------------+---------------------------------------------------------------------------------+----------+ @@ -29,8 +31,6 @@ Properties +---------------------------+---------------------------------------------------------------------------------+----------+ | :ref:`bool` | :ref:`print_error_messages` | ``true`` | +---------------------------+---------------------------------------------------------------------------------+----------+ -| :ref:`int` | :ref:`target_fps` | ``0`` | -+---------------------------+---------------------------------------------------------------------------------+----------+ | :ref:`float` | :ref:`time_scale` | ``1.0`` | +---------------------------+---------------------------------------------------------------------------------+----------+ @@ -90,6 +90,32 @@ Methods Property Descriptions --------------------- +.. _class_Engine_property_max_fps: + +- :ref:`int` **max_fps** + ++-----------+--------------------+ +| *Default* | ``0`` | ++-----------+--------------------+ +| *Setter* | set_max_fps(value) | ++-----------+--------------------+ +| *Getter* | get_max_fps() | ++-----------+--------------------+ + +The maximum number of frames per second that can be rendered. A value of ``0`` means "no limit". The actual number of frames per second may still be below this value if the CPU or GPU cannot keep up with the project logic and rendering. + +Limiting the FPS can be useful to reduce system power consumption, which reduces heat and noise emissions (and improves battery life on mobile devices). + +If :ref:`ProjectSettings.display/window/vsync/vsync_mode` is ``Enabled`` or ``Adaptive``, it takes precedence and the forced FPS number cannot exceed the monitor's refresh rate. + +If :ref:`ProjectSettings.display/window/vsync/vsync_mode` is ``Enabled``, on monitors with variable refresh rate enabled (G-Sync/FreeSync), using a FPS limit a few frames lower than the monitor's refresh rate will `reduce input lag while avoiding tearing `__. + +If :ref:`ProjectSettings.display/window/vsync/vsync_mode` is ``Disabled``, limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios. + +See also :ref:`physics_ticks_per_second` and :ref:`ProjectSettings.application/run/max_fps`. + +---- + .. _class_Engine_property_physics_jitter_fix: - :ref:`float` **physics_jitter_fix** @@ -120,7 +146,7 @@ Controls how much physics ticks are synchronized with real time. For 0 or less, | *Getter* | get_physics_ticks_per_second() | +-----------+-------------------------------------+ -The number of fixed iterations per second. This controls how often physics simulation and :ref:`Node._physics_process` methods are run. This value should generally always be set to ``60`` or above, as Godot doesn't interpolate the physics step. As a result, values lower than ``60`` will look stuttery. This value can be increased to make input more reactive or work around collision tunneling issues, but keep in mind doing so will increase CPU usage. See also :ref:`target_fps` and :ref:`ProjectSettings.physics/common/physics_ticks_per_second`. +The number of fixed iterations per second. This controls how often physics simulation and :ref:`Node._physics_process` methods are run. This value should generally always be set to ``60`` or above, as Godot doesn't interpolate the physics step. As a result, values lower than ``60`` will look stuttery. This value can be increased to make input more reactive or work around collision tunneling issues, but keep in mind doing so will increase CPU usage. See also :ref:`max_fps` and :ref:`ProjectSettings.physics/common/physics_ticks_per_second`. \ **Note:** Only 8 physics ticks may be simulated per rendered frame at most. If more than 8 physics ticks have to be simulated per rendered frame to keep up with rendering, the game will appear to slow down (even if ``delta`` is used consistently in physics calculations). Therefore, it is recommended not to increase :ref:`physics_ticks_per_second` above 240. Otherwise, the game will slow down when the rendering framerate goes below 30 FPS. @@ -146,22 +172,6 @@ If ``false``, stops printing error and warning messages to the console and edito ---- -.. _class_Engine_property_target_fps: - -- :ref:`int` **target_fps** - -+-----------+-----------------------+ -| *Default* | ``0`` | -+-----------+-----------------------+ -| *Setter* | set_target_fps(value) | -+-----------+-----------------------+ -| *Getter* | get_target_fps() | -+-----------+-----------------------+ - -The desired frames per second. If the hardware cannot keep up, this setting may not be respected. A value of 0 means no limit. See also :ref:`physics_ticks_per_second` and :ref:`ProjectSettings.debug/settings/fps/force_fps`. - ----- - .. _class_Engine_property_time_scale: - :ref:`float` **time_scale** @@ -187,13 +197,25 @@ Returns the name of the CPU architecture the Godot binary was built for. Possibl To detect whether the current CPU architecture is 64-bit, you can use the fact that all 64-bit architecture names have ``64`` in their name: -:: + +.. tabs:: + + .. code-tab:: gdscript if "64" in Engine.get_architecture_name(): print("Running on 64-bit CPU.") else: print("Running on 32-bit CPU.") + .. code-tab:: csharp + + if (Engine.GetArchitectureName().Contains("64")) + GD.Print("Running on 64-bit CPU."); + else + GD.Print("Running on 32-bit CPU."); + + + \ **Note:** :ref:`get_architecture_name` does *not* return the name of the host CPU architecture. For example, if running an x86_32 Godot binary on a x86_64 system, the returned value will be ``x86_32``. ---- @@ -284,12 +306,29 @@ Returns the total number of frames passed since engine initialization which is a \ :ref:`get_physics_frames` can be used to run expensive logic less often without relying on a :ref:`Timer`: -:: + +.. tabs:: + + .. code-tab:: gdscript func _physics_process(_delta): if Engine.get_physics_frames() % 2 == 0: pass # Run expensive logic only once every 2 physics frames here. + .. code-tab:: csharp + + public override void _PhysicsProcess(double delta) + { + base._PhysicsProcess(delta); + + if (Engine.GetPhysicsFrames() % 2 == 0) + { + // Run expensive logic only once every 2 physics frames here. + } + } + + + ---- .. _class_Engine_method_get_physics_interpolation_fraction: @@ -308,12 +347,29 @@ Returns the total number of frames passed since engine initialization which is a \ :ref:`get_process_frames` can be used to run expensive logic less often without relying on a :ref:`Timer`: -:: + +.. tabs:: + + .. code-tab:: gdscript func _process(_delta): if Engine.get_process_frames() % 2 == 0: pass # Run expensive logic only once every 2 process (render) frames here. + .. code-tab:: csharp + + public override void _Process(double delta) + { + base._Process(delta); + + if (Engine.GetProcessFrames() % 2 == 0) + { + // Run expensive logic only once every 2 physics frames here. + } + } + + + ---- .. _class_Engine_method_get_script_language: @@ -415,13 +471,25 @@ Returns ``true`` if a singleton with given ``name`` exists in global scope. Returns ``true`` if the script is currently running inside the editor, ``false`` otherwise. This is useful for ``@tool`` scripts to conditionally draw editor helpers, or prevent accidentally running "game" code that would affect the scene state while in the editor: -:: + +.. tabs:: + + .. code-tab:: gdscript if Engine.is_editor_hint(): draw_gizmos() else: simulate_physics() + .. code-tab:: csharp + + if (Engine.IsEditorHint()) + DrawGizmos(); + else + SimulatePhysics(); + + + See :doc:`Running code in the editor <../tutorials/plugins/running_code_in_the_editor>` in the documentation for more information. \ **Note:** To detect whether the script is run from an editor *build* (e.g. when pressing :kbd:`F5`), use :ref:`OS.has_feature` with the ``"editor"`` argument instead. ``OS.has_feature("editor")`` will evaluate to ``true`` both when the code is running in the editor and when running the project from the editor, but it will evaluate to ``false`` when the code is run from an exported project. diff --git a/classes/class_environment.rst b/classes/class_environment.rst index df37fe849..62e1b4824 100644 --- a/classes/class_environment.rst +++ b/classes/class_environment.rst @@ -658,7 +658,7 @@ This is useful to simulate `aerial perspective ` of the volumetric fog when interacting with lights | *Getter* | get_volumetric_fog_ambient_inject() | +-----------+------------------------------------------+ -Scales the strength of ambient light used in the volumetric fog. A value of ``0`` means that ambient light will not impact the volumetric fog. +Scales the strength of ambient light used in the volumetric fog. A value of ``0.0`` means that ambient light will not impact the volumetric fog. :ref:`volumetric_fog_ambient_inject` has a small performance cost when set above ``0.0``. + +\ **Note:** This has no visible effect if :ref:`volumetric_fog_density` is ``0.0`` or if :ref:`volumetric_fog_albedo` is a fully black color. ---- @@ -1742,7 +1744,7 @@ Scales the strength of ambient light used in the volumetric fog. A value of ``0` | *Getter* | get_volumetric_fog_anisotropy() | +-----------+--------------------------------------+ -The direction of scattered light as it goes through the volumetric fog. A value close ``1`` means almost all light is scattered forward. A value close to ``0`` means light is scattered equally in all directions. A value close to ``-1`` means light is scattered mostly backward. Fog and mist scatter light slightly forward, while smoke scatters light equally in all directions. +The direction of scattered light as it goes through the volumetric fog. A value close to ``1.0`` means almost all light is scattered forward. A value close to ``0.0`` means light is scattered equally in all directions. A value close to ``-1.0`` means light is scattered mostly backward. Fog and mist scatter light slightly forward, while smoke scatters light equally in all directions. ---- @@ -1758,7 +1760,9 @@ The direction of scattered light as it goes through the volumetric fog. A value | *Getter* | get_volumetric_fog_density() | +-----------+-----------------------------------+ -The base density of the volumetric fog. Set this to the lowest density you want to have globally. +The base *exponential* density of the volumetric fog. Set this to the lowest density you want to have globally. :ref:`FogVolume`\ s can be used to add to or subtract from this density in specific areas. Fog rendering is exponential as in real life. + +A value of ``0.0`` disables global volumetric fog while allowing :ref:`FogVolume`\ s to display volumetric fog in specific areas. ---- @@ -1824,6 +1828,8 @@ The brightness of the emitted light from the volumetric fog. Enables the volumetric fog effect. Volumetric fog uses a screen-aligned froxel buffer to calculate accurate volumetric scattering in the short to medium range. Volumetric fog interacts with :ref:`FogVolume`\ s and lights to calculate localized and global fog. Volumetric fog uses a PBR single-scattering model based on extinction, scattering, and emission which it exposes to users as density, albedo, and emission. +\ **Note:** Volumetric fog is only available in the forward plus renderer. It is not available in the mobile renderer or the compatibility renderer. + ---- .. _class_Environment_property_volumetric_fog_gi_inject: @@ -1838,7 +1844,9 @@ Enables the volumetric fog effect. Volumetric fog uses a screen-aligned froxel b | *Getter* | get_volumetric_fog_gi_inject() | +-----------+-------------------------------------+ -Scales the strength of Global Illumination used in the volumetric fog. A value of ``0.0`` means that Global Illumination will not impact the volumetric fog. +Scales the strength of Global Illumination used in the volumetric fog's albedo color. A value of ``0.0`` means that Global Illumination will not impact the volumetric fog. :ref:`volumetric_fog_gi_inject` has a small performance cost when set above ``0.0``. + +\ **Note:** This has no visible effect if :ref:`volumetric_fog_density` is ``0.0`` or if :ref:`volumetric_fog_albedo` is a fully black color. \ **Note:** Only :ref:`VoxelGI` and SDFGI (:ref:`sdfgi_enabled`) are taken into account when using :ref:`volumetric_fog_gi_inject`. Global illumination from :ref:`LightmapGI`, :ref:`ReflectionProbe` and SSIL (see :ref:`ssil_enabled`) will be ignored by volumetric fog. @@ -1856,7 +1864,7 @@ Scales the strength of Global Illumination used in the volumetric fog. A value o | *Getter* | get_volumetric_fog_length() | +-----------+----------------------------------+ -The distance over which the volumetric fog is computed. Increase to compute fog over a greater range, decrease to add more detail when a long range is not needed. For best quality fog, keep this as low as possible. +The distance over which the volumetric fog is computed. Increase to compute fog over a greater range, decrease to add more detail when a long range is not needed. For best quality fog, keep this as low as possible. See also :ref:`ProjectSettings.rendering/environment/volumetric_fog/volume_depth`. ---- @@ -1874,6 +1882,8 @@ The distance over which the volumetric fog is computed. Increase to compute fog The factor to use when affecting the sky with volumetric fog. ``1.0`` means that volumetric fog can fully obscure the sky. Lower values reduce the impact of volumetric fog on sky rendering, with ``0.0`` not affecting sky rendering at all. +\ **Note:** :ref:`volumetric_fog_sky_affect` also affects :ref:`FogVolume`\ s, even if :ref:`volumetric_fog_density` is ``0.0``. If you notice :ref:`FogVolume`\ s are disappearing when looking towards the sky, set :ref:`volumetric_fog_sky_affect` to ``1.0``. + ---- .. _class_Environment_property_volumetric_fog_temporal_reprojection_amount: @@ -1904,7 +1914,7 @@ The amount by which to blend the last frame with the current frame. A higher num | *Getter* | is_volumetric_fog_temporal_reprojection_enabled() | +-----------+---------------------------------------------------------+ -Enables temporal reprojection in the volumetric fog. Temporal reprojection blends the current frame's volumetric fog with the last frame's volumetric fog to smooth out jagged edges. The performance cost is minimal, however it does lead to moving :ref:`FogVolume`\ s and :ref:`Light3D`\ s "ghosting" and leaving a trail behind them. When temporal reprojection is enabled, try to avoid moving :ref:`FogVolume`\ s or :ref:`Light3D`\ s too fast. +Enables temporal reprojection in the volumetric fog. Temporal reprojection blends the current frame's volumetric fog with the last frame's volumetric fog to smooth out jagged edges. The performance cost is minimal; however, it leads to moving :ref:`FogVolume`\ s and :ref:`Light3D`\ s "ghosting" and leaving a trail behind them. When temporal reprojection is enabled, try to avoid moving :ref:`FogVolume`\ s or :ref:`Light3D`\ s too fast. Short-lived dynamic lighting effects should have :ref:`Light3D.light_volumetric_fog_energy` set to ``0.0`` to avoid ghosting. Method Descriptions ------------------- diff --git a/classes/class_file.rst b/classes/class_fileaccess.rst similarity index 63% rename from classes/class_file.rst rename to classes/class_fileaccess.rst index 407af247d..de043ad72 100644 --- a/classes/class_file.rst +++ b/classes/class_fileaccess.rst @@ -3,12 +3,12 @@ .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. -.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/File.xml. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/FileAccess.xml. -.. _class_File: +.. _class_FileAccess: -File -==== +FileAccess +========== **Inherits:** :ref:`RefCounted` **<** :ref:`Object` @@ -27,34 +27,26 @@ Here's a sample on how to write and read from a file: .. code-tab:: gdscript func save(content): - var file = File.new() - file.open("user://save_game.dat", File.WRITE) + var file = FileAccess.open("user://save_game.dat", FileAccess.WRITE) file.store_string(content) - file.close() func load(): - var file = File.new() - file.open("user://save_game.dat", File.READ) + var file = FileAccess.open("user://save_game.dat", FileAccess.READ) var content = file.get_as_text() - file.close() return content .. code-tab:: csharp public void Save(string content) { - var file = new File(); - file.Open("user://save_game.dat", File.ModeFlags.Write); + using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Write); file.StoreString(content); - file.Close(); } public string Load() { - var file = new File(); - file.Open("user://save_game.dat", File.ModeFlags.Read); + using var file = FileAccess.Open("user://save_game.dat", FileAccess.ModeFlags.Read); string content = file.GetAsText(); - file.Close(); return content; } @@ -62,9 +54,26 @@ 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. -\ **Note:** To access project resources once exported, it is recommended to use :ref:`ResourceLoader` instead of the ``File`` API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. +There is no method to close a file in order to free it from use. Instead, ``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. -\ **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. + +.. 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:** 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. Tutorials --------- @@ -76,117 +85,117 @@ Tutorials Properties ---------- -+-------------------------+---------------------------------------------------+-----------+ -| :ref:`bool` | :ref:`big_endian` | ``false`` | -+-------------------------+---------------------------------------------------+-----------+ ++-------------------------+---------------------------------------------------------+ +| :ref:`bool` | :ref:`big_endian` | ++-------------------------+---------------------------------------------------------+ Methods ------- -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`close` **(** **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`eof_reached` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`file_exists` **(** :ref:`String` path **)** |static| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`flush` **(** **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_16` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_32` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_64` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_8` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_as_text` **(** :ref:`bool` skip_cr=false **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedByteArray` | :ref:`get_buffer` **(** :ref:`int` length **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`PackedStringArray` | :ref:`get_csv_line` **(** :ref:`String` delim="," **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_double` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`get_error` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_float` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_length` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_line` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_md5` **(** :ref:`String` path **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_modified_time` **(** :ref:`String` file **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_pascal_string` **(** **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_path` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_path_absolute` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`int` | :ref:`get_position` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`float` | :ref:`get_real` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`String` | :ref:`get_sha256` **(** :ref:`String` path **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Variant` | :ref:`get_var` **(** :ref:`bool` allow_objects=false **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`bool` | :ref:`is_open` **(** **)** |const| | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`open` **(** :ref:`String` path, :ref:`ModeFlags` flags **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`open_compressed` **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`CompressionMode` compression_mode=0 **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`open_encrypted` **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`PackedByteArray` key **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| :ref:`Error` | :ref:`open_encrypted_with_pass` **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`String` pass **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`seek` **(** :ref:`int` position **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`seek_end` **(** :ref:`int` position=0 **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_16` **(** :ref:`int` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_32` **(** :ref:`int` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_64` **(** :ref:`int` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_8` **(** :ref:`int` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_buffer` **(** :ref:`PackedByteArray` buffer **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_csv_line` **(** :ref:`PackedStringArray` values, :ref:`String` delim="," **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_double` **(** :ref:`float` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_float` **(** :ref:`float` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_line` **(** :ref:`String` line **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_pascal_string` **(** :ref:`String` string **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_real` **(** :ref:`float` value **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_string` **(** :ref:`String` string **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| void | :ref:`store_var` **(** :ref:`Variant` value, :ref:`bool` full_objects=false **)** | -+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`eof_reached` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`file_exists` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`flush` **(** **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_16` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_32` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_64` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_8` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_as_text` **(** :ref:`bool` skip_cr=false **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedByteArray` | :ref:`get_buffer` **(** :ref:`int` length **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`PackedStringArray` | :ref:`get_csv_line` **(** :ref:`String` delim="," **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_double` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`get_error` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_float` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_length` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_line` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_md5` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_modified_time` **(** :ref:`String` file **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Error` | :ref:`get_open_error` **(** **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_pascal_string` **(** **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_path` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_path_absolute` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`int` | :ref:`get_position` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`float` | :ref:`get_real` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`String` | :ref:`get_sha256` **(** :ref:`String` path **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`Variant` | :ref:`get_var` **(** :ref:`bool` allow_objects=false **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`bool` | :ref:`is_open` **(** **)** |const| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`FileAccess` | :ref:`open` **(** :ref:`String` path, :ref:`ModeFlags` flags **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`FileAccess` | :ref:`open_compressed` **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`CompressionMode` compression_mode=0 **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`FileAccess` | :ref:`open_encrypted` **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`PackedByteArray` key **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| :ref:`FileAccess` | :ref:`open_encrypted_with_pass` **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`String` pass **)** |static| | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`seek` **(** :ref:`int` position **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`seek_end` **(** :ref:`int` position=0 **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_16` **(** :ref:`int` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_32` **(** :ref:`int` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_64` **(** :ref:`int` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_8` **(** :ref:`int` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_buffer` **(** :ref:`PackedByteArray` buffer **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_csv_line` **(** :ref:`PackedStringArray` values, :ref:`String` delim="," **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_double` **(** :ref:`float` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_float` **(** :ref:`float` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_line` **(** :ref:`String` line **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_pascal_string` **(** :ref:`String` string **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_real` **(** :ref:`float` value **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_string` **(** :ref:`String` string **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| void | :ref:`store_var` **(** :ref:`Variant` value, :ref:`bool` full_objects=false **)** | ++---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Enumerations ------------ -.. _enum_File_ModeFlags: +.. _enum_FileAccess_ModeFlags: -.. _class_File_constant_READ: +.. _class_FileAccess_constant_READ: -.. _class_File_constant_WRITE: +.. _class_FileAccess_constant_WRITE: -.. _class_File_constant_READ_WRITE: +.. _class_FileAccess_constant_READ_WRITE: -.. _class_File_constant_WRITE_READ: +.. _class_FileAccess_constant_WRITE_READ: enum **ModeFlags**: @@ -200,15 +209,15 @@ enum **ModeFlags**: ---- -.. _enum_File_CompressionMode: +.. _enum_FileAccess_CompressionMode: -.. _class_File_constant_COMPRESSION_FASTLZ: +.. _class_FileAccess_constant_COMPRESSION_FASTLZ: -.. _class_File_constant_COMPRESSION_DEFLATE: +.. _class_FileAccess_constant_COMPRESSION_DEFLATE: -.. _class_File_constant_COMPRESSION_ZSTD: +.. _class_FileAccess_constant_COMPRESSION_ZSTD: -.. _class_File_constant_COMPRESSION_GZIP: +.. _class_FileAccess_constant_COMPRESSION_GZIP: enum **CompressionMode**: @@ -223,36 +232,26 @@ enum **CompressionMode**: Property Descriptions --------------------- -.. _class_File_property_big_endian: +.. _class_FileAccess_property_big_endian: - :ref:`bool` **big_endian** -+-----------+-----------------------+ -| *Default* | ``false`` | -+-----------+-----------------------+ -| *Setter* | set_big_endian(value) | -+-----------+-----------------------+ -| *Getter* | is_big_endian() | -+-----------+-----------------------+ ++----------+-----------------------+ +| *Setter* | set_big_endian(value) | ++----------+-----------------------+ +| *Getter* | is_big_endian() | ++----------+-----------------------+ If ``true``, the file is read with big-endian `endianness `__. If ``false``, the file is read with little-endian endianness. If in doubt, leave this to ``false`` as most files are written with little-endian endianness. -\ **Note:** :ref:`big_endian` is only about the file format, not the CPU type. The CPU endianness doesn't affect the default endianness for files written. +\ **Note:** :ref:`big_endian` is only about the file format, not the CPU type. The CPU endianness doesn't affect the default endianness for files written. -\ **Note:** This is always reset to ``false`` whenever you open the file. Therefore, you must set :ref:`big_endian` *after* opening the file, not before. +\ **Note:** This is always reset to ``false`` whenever you open the file. Therefore, you must set :ref:`big_endian` *after* opening the file, not before. Method Descriptions ------------------- -.. _class_File_method_close: - -- void **close** **(** **)** - -Closes the currently opened file and prevents subsequent read/write operations. Use :ref:`flush` to persist the data to disk without closing the file. - ----- - -.. _class_File_method_eof_reached: +.. _class_FileAccess_method_eof_reached: - :ref:`bool` **eof_reached** **(** **)** |const| @@ -279,7 +278,7 @@ Returns ``true`` if the file cursor has already read past the end of the file. ---- -.. _class_File_method_file_exists: +.. _class_FileAccess_method_file_exists: - :ref:`bool` **file_exists** **(** :ref:`String` path **)** |static| @@ -287,51 +286,53 @@ Returns ``true`` if the file exists in the given path. \ **Note:** Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See :ref:`ResourceLoader.exists` for an alternative approach that takes resource remapping into account. +For a non-static, relative equivalent, use :ref:`DirAccess.file_exists`. + ---- -.. _class_File_method_flush: +.. _class_FileAccess_method_flush: - void **flush** **(** **)** -Writes the file's buffer to disk. Flushing is automatically performed when the file is closed. This means you don't need to call :ref:`flush` manually before closing a file using :ref:`close`. Still, calling :ref:`flush` can be used to ensure the data is safe even if the project crashes instead of being closed gracefully. +Writes the file's buffer to disk. Flushing is automatically performed when the file is closed. This means you don't need to call :ref:`flush` manually before closing a file. Still, calling :ref:`flush` can be used to ensure the data is safe even if the project crashes instead of being closed gracefully. -\ **Note:** Only call :ref:`flush` when you actually need it. Otherwise, it will decrease performance due to constant disk writes. +\ **Note:** Only call :ref:`flush` when you actually need it. Otherwise, it will decrease performance due to constant disk writes. ---- -.. _class_File_method_get_16: +.. _class_FileAccess_method_get_16: - :ref:`int` **get_16** **(** **)** |const| -Returns the next 16 bits from the file as an integer. See :ref:`store_16` for details on what values can be stored and retrieved this way. +Returns the next 16 bits from the file as an integer. See :ref:`store_16` for details on what values can be stored and retrieved this way. ---- -.. _class_File_method_get_32: +.. _class_FileAccess_method_get_32: - :ref:`int` **get_32** **(** **)** |const| -Returns the next 32 bits from the file as an integer. See :ref:`store_32` for details on what values can be stored and retrieved this way. +Returns the next 32 bits from the file as an integer. See :ref:`store_32` for details on what values can be stored and retrieved this way. ---- -.. _class_File_method_get_64: +.. _class_FileAccess_method_get_64: - :ref:`int` **get_64** **(** **)** |const| -Returns the next 64 bits from the file as an integer. See :ref:`store_64` for details on what values can be stored and retrieved this way. +Returns the next 64 bits from the file as an integer. See :ref:`store_64` for details on what values can be stored and retrieved this way. ---- -.. _class_File_method_get_8: +.. _class_FileAccess_method_get_8: - :ref:`int` **get_8** **(** **)** |const| -Returns the next 8 bits from the file as an integer. See :ref:`store_8` for details on what values can be stored and retrieved this way. +Returns the next 8 bits from the file as an integer. See :ref:`store_8` for details on what values can be stored and retrieved this way. ---- -.. _class_File_method_get_as_text: +.. _class_FileAccess_method_get_as_text: - :ref:`String` **get_as_text** **(** :ref:`bool` skip_cr=false **)** |const| @@ -341,7 +342,7 @@ If ``skip_cr`` is ``true``, carriage return characters (``\r``, CR) will be igno ---- -.. _class_File_method_get_buffer: +.. _class_FileAccess_method_get_buffer: - :ref:`PackedByteArray` **get_buffer** **(** :ref:`int` length **)** |const| @@ -349,7 +350,7 @@ Returns next ``length`` bytes of the file as a :ref:`PackedByteArray` **get_csv_line** **(** :ref:`String` delim="," **)** |const| @@ -369,7 +370,7 @@ Note how the second line can omit the enclosing quotes as it does not include th ---- -.. _class_File_method_get_double: +.. _class_FileAccess_method_get_double: - :ref:`float` **get_double** **(** **)** |const| @@ -377,7 +378,7 @@ Returns the next 64 bits from the file as a floating-point number. ---- -.. _class_File_method_get_error: +.. _class_FileAccess_method_get_error: - :ref:`Error` **get_error** **(** **)** |const| @@ -385,7 +386,7 @@ Returns the last error that happened when trying to perform operations. Compare ---- -.. _class_File_method_get_float: +.. _class_FileAccess_method_get_float: - :ref:`float` **get_float** **(** **)** |const| @@ -393,7 +394,7 @@ Returns the next 32 bits from the file as a floating-point number. ---- -.. _class_File_method_get_length: +.. _class_FileAccess_method_get_length: - :ref:`int` **get_length** **(** **)** |const| @@ -401,7 +402,7 @@ Returns the size of the file in bytes. ---- -.. _class_File_method_get_line: +.. _class_FileAccess_method_get_line: - :ref:`String` **get_line** **(** **)** |const| @@ -411,23 +412,31 @@ Text is interpreted as being UTF-8 encoded. ---- -.. _class_File_method_get_md5: +.. _class_FileAccess_method_get_md5: -- :ref:`String` **get_md5** **(** :ref:`String` path **)** |const| +- :ref:`String` **get_md5** **(** :ref:`String` path **)** |static| Returns an MD5 String representing the file at the given path or an empty :ref:`String` on failure. ---- -.. _class_File_method_get_modified_time: +.. _class_FileAccess_method_get_modified_time: -- :ref:`int` **get_modified_time** **(** :ref:`String` file **)** |const| +- :ref:`int` **get_modified_time** **(** :ref:`String` file **)** |static| Returns the last time the ``file`` was modified in Unix timestamp format or returns a :ref:`String` "ERROR IN ``file``". This Unix timestamp can be converted to another format using the :ref:`Time` singleton. ---- -.. _class_File_method_get_pascal_string: +.. _class_FileAccess_method_get_open_error: + +- :ref:`Error` **get_open_error** **(** **)** |static| + +Returns the result of the last :ref:`open` call in the current thread. + +---- + +.. _class_FileAccess_method_get_pascal_string: - :ref:`String` **get_pascal_string** **(** **)** @@ -437,7 +446,7 @@ Text is interpreted as being UTF-8 encoded. ---- -.. _class_File_method_get_path: +.. _class_FileAccess_method_get_path: - :ref:`String` **get_path** **(** **)** |const| @@ -445,7 +454,7 @@ Returns the path as a :ref:`String` for the current open file. ---- -.. _class_File_method_get_path_absolute: +.. _class_FileAccess_method_get_path_absolute: - :ref:`String` **get_path_absolute** **(** **)** |const| @@ -453,7 +462,7 @@ Returns the absolute path as a :ref:`String` for the current open ---- -.. _class_File_method_get_position: +.. _class_FileAccess_method_get_position: - :ref:`int` **get_position** **(** **)** |const| @@ -461,7 +470,7 @@ Returns the file cursor's position. ---- -.. _class_File_method_get_real: +.. _class_FileAccess_method_get_real: - :ref:`float` **get_real** **(** **)** |const| @@ -469,15 +478,15 @@ Returns the next bits from the file as a floating-point number. ---- -.. _class_File_method_get_sha256: +.. _class_FileAccess_method_get_sha256: -- :ref:`String` **get_sha256** **(** :ref:`String` path **)** |const| +- :ref:`String` **get_sha256** **(** :ref:`String` path **)** |static| Returns a SHA-256 :ref:`String` representing the file at the given path or an empty :ref:`String` on failure. ---- -.. _class_File_method_get_var: +.. _class_FileAccess_method_get_var: - :ref:`Variant` **get_var** **(** :ref:`bool` allow_objects=false **)** |const| @@ -487,7 +496,7 @@ Returns the next :ref:`Variant` value from the file. If ``allow_o ---- -.. _class_File_method_is_open: +.. _class_FileAccess_method_is_open: - :ref:`bool` **is_open** **(** **)** |const| @@ -495,43 +504,51 @@ Returns ``true`` if the file is currently opened. ---- -.. _class_File_method_open: +.. _class_FileAccess_method_open: -- :ref:`Error` **open** **(** :ref:`String` path, :ref:`ModeFlags` flags **)** +- :ref:`FileAccess` **open** **(** :ref:`String` path, :ref:`ModeFlags` flags **)** |static| -Opens the file for writing or reading, depending on the flags. +Creates a new ``FileAccess`` object and opens the file for writing or reading, depending on the flags. + +Returns ``null`` if opening the file failed. You can use :ref:`get_open_error` to check the error that occurred. ---- -.. _class_File_method_open_compressed: +.. _class_FileAccess_method_open_compressed: -- :ref:`Error` **open_compressed** **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`CompressionMode` compression_mode=0 **)** +- :ref:`FileAccess` **open_compressed** **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`CompressionMode` compression_mode=0 **)** |static| -Opens a compressed file for reading or writing. +Creates a new ``FileAccess`` object and opens a compressed file for reading or writing. -\ **Note:** :ref:`open_compressed` can only read files that were saved by Godot, not third-party compression formats. See `GitHub issue #28999 `__ for a workaround. +\ **Note:** :ref:`open_compressed` can only read files that were saved by Godot, not third-party compression formats. See `GitHub issue #28999 `__ for a workaround. + +Returns ``null`` if opening the file failed. You can use :ref:`get_open_error` to check the error that occurred. ---- -.. _class_File_method_open_encrypted: +.. _class_FileAccess_method_open_encrypted: -- :ref:`Error` **open_encrypted** **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`PackedByteArray` key **)** +- :ref:`FileAccess` **open_encrypted** **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`PackedByteArray` key **)** |static| -Opens an encrypted file in write or read mode. You need to pass a binary key to encrypt/decrypt it. +Creates a new ``FileAccess`` object and opens an encrypted file in write or read mode. You need to pass a binary key to encrypt/decrypt it. \ **Note:** The provided key must be 32 bytes long. ----- - -.. _class_File_method_open_encrypted_with_pass: - -- :ref:`Error` **open_encrypted_with_pass** **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`String` pass **)** - -Opens an encrypted file in write or read mode. You need to pass a password to encrypt/decrypt it. +Returns ``null`` if opening the file failed. You can use :ref:`get_open_error` to check the error that occurred. ---- -.. _class_File_method_seek: +.. _class_FileAccess_method_open_encrypted_with_pass: + +- :ref:`FileAccess` **open_encrypted_with_pass** **(** :ref:`String` path, :ref:`ModeFlags` mode_flags, :ref:`String` pass **)** |static| + +Creates a new ``FileAccess`` object and opens an encrypted file in write or read mode. You need to pass a password to encrypt/decrypt it. + +Returns ``null`` if opening the file failed. You can use :ref:`get_open_error` to check the error that occurred. + +---- + +.. _class_FileAccess_method_seek: - void **seek** **(** :ref:`int` position **)** @@ -539,7 +556,7 @@ Changes the file reading/writing cursor to the specified position (in bytes from ---- -.. _class_File_method_seek_end: +.. _class_FileAccess_method_seek_end: - void **seek_end** **(** :ref:`int` position=0 **)** @@ -549,7 +566,7 @@ Changes the file reading/writing cursor to the specified position (in bytes from ---- -.. _class_File_method_store_16: +.. _class_FileAccess_method_store_16: - void **store_16** **(** :ref:`int` value **)** @@ -557,7 +574,7 @@ Stores an integer as 16 bits in the file. \ **Note:** The ``value`` should lie in the interval ``[0, 2^16 - 1]``. Any other value will overflow and wrap around. -To store a signed integer, use :ref:`store_64` or store a signed integer from the interval ``[-2^15, 2^15 - 1]`` (i.e. keeping one bit for the signedness) and compute its sign manually when reading. For example: +To store a signed integer, use :ref:`store_64` or store a signed integer from the interval ``[-2^15, 2^15 - 1]`` (i.e. keeping one bit for the signedness) and compute its sign manually when reading. For example: .. tabs:: @@ -571,8 +588,7 @@ To store a signed integer, use :ref:`store_64` or st return (unsigned + MAX_15B) % MAX_16B - MAX_15B func _ready(): - var f = File.new() - f.open("user://file.dat", File.WRITE_READ) + var f = FileAccess.open("user://file.dat", FileAccess.WRITE_READ) f.store_16(-42) # This wraps around and stores 65494 (2^16 - 42). f.store_16(121) # In bounds, will store 121. f.seek(0) # Go back to start to read the stored value. @@ -585,8 +601,7 @@ To store a signed integer, use :ref:`store_64` or st public override void _Ready() { - var f = new File(); - f.Open("user://file.dat", File.ModeFlags.WriteRead); + using var f = FileAccess.Open("user://file.dat", FileAccess.ModeFlags.WriteRead); f.Store16(unchecked((ushort)-42)); // This wraps around and stores 65494 (2^16 - 42). f.Store16(121); // In bounds, will store 121. f.Seek(0); // Go back to start to read the stored value. @@ -600,7 +615,7 @@ To store a signed integer, use :ref:`store_64` or st ---- -.. _class_File_method_store_32: +.. _class_FileAccess_method_store_32: - void **store_32** **(** :ref:`int` value **)** @@ -608,11 +623,11 @@ Stores an integer as 32 bits in the file. \ **Note:** The ``value`` should lie in the interval ``[0, 2^32 - 1]``. Any other value will overflow and wrap around. -To store a signed integer, use :ref:`store_64`, or convert it manually (see :ref:`store_16` for an example). +To store a signed integer, use :ref:`store_64`, or convert it manually (see :ref:`store_16` for an example). ---- -.. _class_File_method_store_64: +.. _class_FileAccess_method_store_64: - void **store_64** **(** :ref:`int` value **)** @@ -622,7 +637,7 @@ Stores an integer as 64 bits in the file. ---- -.. _class_File_method_store_8: +.. _class_FileAccess_method_store_8: - void **store_8** **(** :ref:`int` value **)** @@ -630,11 +645,11 @@ Stores an integer as 8 bits in the file. \ **Note:** The ``value`` should lie in the interval ``[0, 255]``. Any other value will overflow and wrap around. -To store a signed integer, use :ref:`store_64`, or convert it manually (see :ref:`store_16` for an example). +To store a signed integer, use :ref:`store_64`, or convert it manually (see :ref:`store_16` for an example). ---- -.. _class_File_method_store_buffer: +.. _class_FileAccess_method_store_buffer: - void **store_buffer** **(** :ref:`PackedByteArray` buffer **)** @@ -642,7 +657,7 @@ Stores the given array of bytes in the file. ---- -.. _class_File_method_store_csv_line: +.. _class_FileAccess_method_store_csv_line: - void **store_csv_line** **(** :ref:`PackedStringArray` values, :ref:`String` delim="," **)** @@ -652,7 +667,7 @@ Text will be encoded as UTF-8. ---- -.. _class_File_method_store_double: +.. _class_FileAccess_method_store_double: - void **store_double** **(** :ref:`float` value **)** @@ -660,7 +675,7 @@ Stores a floating-point number as 64 bits in the file. ---- -.. _class_File_method_store_float: +.. _class_FileAccess_method_store_float: - void **store_float** **(** :ref:`float` value **)** @@ -668,7 +683,7 @@ Stores a floating-point number as 32 bits in the file. ---- -.. _class_File_method_store_line: +.. _class_FileAccess_method_store_line: - void **store_line** **(** :ref:`String` line **)** @@ -676,7 +691,7 @@ Appends ``line`` to the file followed by a line return character (``\n``), encod ---- -.. _class_File_method_store_pascal_string: +.. _class_FileAccess_method_store_pascal_string: - void **store_pascal_string** **(** :ref:`String` string **)** @@ -686,7 +701,7 @@ Text will be encoded as UTF-8. ---- -.. _class_File_method_store_real: +.. _class_FileAccess_method_store_real: - void **store_real** **(** :ref:`float` value **)** @@ -694,17 +709,17 @@ Stores a floating-point number in the file. ---- -.. _class_File_method_store_string: +.. _class_FileAccess_method_store_string: - void **store_string** **(** :ref:`String` string **)** Appends ``string`` to the file without a line return, encoding the text as UTF-8. -\ **Note:** This method is intended to be used to write text files. The string is stored as a UTF-8 encoded buffer without string length or terminating zero, which means that it can't be loaded back easily. If you want to store a retrievable string in a binary file, consider using :ref:`store_pascal_string` instead. For retrieving strings from a text file, you can use ``get_buffer(length).get_string_from_utf8()`` (if you know the length) or :ref:`get_as_text`. +\ **Note:** This method is intended to be used to write text files. The string is stored as a UTF-8 encoded buffer without string length or terminating zero, which means that it can't be loaded back easily. If you want to store a retrievable string in a binary file, consider using :ref:`store_pascal_string` instead. For retrieving strings from a text file, you can use ``get_buffer(length).get_string_from_utf8()`` (if you know the length) or :ref:`get_as_text`. ---- -.. _class_File_method_store_var: +.. _class_FileAccess_method_store_var: - void **store_var** **(** :ref:`Variant` value, :ref:`bool` full_objects=false **)** diff --git a/classes/class_filesystemdock.rst b/classes/class_filesystemdock.rst index e4cb1e750..fc21b0c71 100644 --- a/classes/class_filesystemdock.rst +++ b/classes/class_filesystemdock.rst @@ -44,7 +44,7 @@ Signals .. _class_FileSystemDock_signal_folder_moved: -- **folder_moved** **(** :ref:`String` old_folder, :ref:`String` new_file **)** +- **folder_moved** **(** :ref:`String` old_folder, :ref:`String` new_folder **)** ---- diff --git a/classes/class_fogmaterial.rst b/classes/class_fogmaterial.rst index b8afcec1f..78a26da79 100644 --- a/classes/class_fogmaterial.rst +++ b/classes/class_fogmaterial.rst @@ -19,6 +19,8 @@ Description A :ref:`Material` resource that can be used by :ref:`FogVolume`\ s to draw volumetric effects. +If you need more advanced effects, use a custom :doc:`fog shader <../tutorials/shaders/shader_reference/fog_shader>`. + Properties ---------- @@ -51,7 +53,7 @@ Property Descriptions | *Getter* | get_albedo() | +-----------+-----------------------+ -Sets the single-scattering :ref:`Color` of the :ref:`FogVolume`. Internally :ref:`albedo` is converted into single-scattering which is additively blended with other :ref:`FogVolume`\ s and the :ref:`Environment.volumetric_fog_albedo`. +The single-scattering :ref:`Color` of the :ref:`FogVolume`. Internally, :ref:`albedo` is converted into single-scattering, which is additively blended with other :ref:`FogVolume`\ s and the :ref:`Environment.volumetric_fog_albedo`. ---- @@ -67,7 +69,7 @@ Sets the single-scattering :ref:`Color` of the :ref:`FogVolume`. Denser objects are more opaque, but may suffer from under-sampling artifacts that look like stripes. +The density of the :ref:`FogVolume`. Denser objects are more opaque, but may suffer from under-sampling artifacts that look like stripes. Negative values can be used to subtract fog from other :ref:`FogVolume`\ s or global volumetric fog. ---- @@ -81,7 +83,7 @@ Sets the density of the :ref:`FogVolume`. Denser objects are mo | *Getter* | get_density_texture() | +----------+----------------------------+ -Sets a 3D texture that is used to scale the :ref:`density` of the :ref:`FogVolume`. +The 3D texture that is used to scale the :ref:`density` of the :ref:`FogVolume`. This can be used to vary fog density within the :ref:`FogVolume` with any kind of static pattern. For animated effects, consider using a custom :doc:`fog shader <../tutorials/shaders/shader_reference/fog_shader>`. ---- @@ -97,7 +99,7 @@ Sets a 3D texture that is used to scale the :ref:`density`. A higher number will result in softer edges while a lower number will result in harder edges. +The hardness of the edges of the :ref:`FogVolume`. A higher value will result in softer edges, while a lower value will result in harder edges. ---- @@ -113,7 +115,7 @@ Sets the hardness of the edges of the :ref:`FogVolume`. A highe | *Getter* | get_emission() | +-----------+-----------------------+ -Sets the :ref:`Color` of the light emitted by the :ref:`FogVolume`. Emitted light will not cast light or shadows on other objects, but can be useful for modulating the :ref:`Color` of the :ref:`FogVolume` independently from light sources. +The :ref:`Color` of the light emitted by the :ref:`FogVolume`. Emitted light will not cast light or shadows on other objects, but can be useful for modulating the :ref:`Color` of the :ref:`FogVolume` independently from light sources. ---- @@ -129,7 +131,7 @@ Sets the :ref:`Color` of the light emitted by the :ref:`FogVolume`. +The rate by which the height-based fog decreases in density as height increases in world space. A high falloff will result in a sharp transition, while a low falloff will result in a smoother transition. A value of ``0.0`` results in uniform-density fog. The height threshold is determined by the height of the associated :ref:`FogVolume`. .. |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_fogvolume.rst b/classes/class_fogvolume.rst index d1e162030..5709d1868 100644 --- a/classes/class_fogvolume.rst +++ b/classes/class_fogvolume.rst @@ -17,10 +17,12 @@ A node used to add local fog with the volumetric fog effect. Description ----------- -``FogVolume``\ s are used to add localized fog into the global volumetric fog effect. +``FogVolume``\ s are used to add localized fog into the global volumetric fog effect. ``FogVolume``\ s can also remove volumetric fog from specific areas if using a :ref:`FogMaterial` with a negative :ref:`FogMaterial.density`. Performance of ``FogVolume``\ s is directly related to their relative size on the screen and the complexity of their attached :ref:`FogMaterial`. It is best to keep ``FogVolume``\ s relatively small and simple where possible. +\ **Note:** ``FogVolume``\ s only have a visible effect if :ref:`Environment.volumetric_fog_enabled` is ``true``. If you don't want fog to be globally visible (but only within ``FogVolume`` nodes), set :ref:`Environment.volumetric_fog_density` to ``0.0``. + Properties ---------- @@ -47,7 +49,7 @@ Property Descriptions | *Getter* | get_extents() | +-----------+----------------------+ -Sets the size of the ``FogVolume`` when :ref:`shape` is :ref:`RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CONE`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CYLINDER` or :ref:`RenderingServer.FOG_VOLUME_SHAPE_BOX`. +The size of the ``FogVolume`` when :ref:`shape` is :ref:`RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CONE`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CYLINDER` or :ref:`RenderingServer.FOG_VOLUME_SHAPE_BOX`. \ **Note:** Thin fog volumes may appear to flicker when the camera moves or rotates. This can be alleviated by increasing :ref:`ProjectSettings.rendering/environment/volumetric_fog/volume_depth` (at a performance cost) or by decreasing :ref:`Environment.volumetric_fog_length` (at no performance cost, but at the cost of lower fog range). Alternatively, the ``FogVolume`` can be made thicker and use a lower density in the :ref:`material`. @@ -65,7 +67,7 @@ Sets the size of the ``FogVolume`` when :ref:`shape` to be used by the ``FogVolume``. Can be either a :ref:`FogMaterial` or a custom :ref:`ShaderMaterial`. +The :ref:`Material` used by the ``FogVolume``. Can be either a built-in :ref:`FogMaterial` or a custom :ref:`ShaderMaterial`. ---- @@ -81,7 +83,7 @@ Sets the :ref:`Material` to be used by the ``FogVolume``. Can be | *Getter* | get_shape() | +-----------+------------------+ -Sets the shape of the ``FogVolume`` to either :ref:`RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CONE`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CYLINDER`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_BOX` or :ref:`RenderingServer.FOG_VOLUME_SHAPE_WORLD`. +The shape of the ``FogVolume``. This can be set to either :ref:`RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CONE`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_CYLINDER`, :ref:`RenderingServer.FOG_VOLUME_SHAPE_BOX` or :ref:`RenderingServer.FOG_VOLUME_SHAPE_WORLD`. .. |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_font.rst b/classes/class_font.rst index e282b0eea..18547e9e4 100644 --- a/classes/class_font.rst +++ b/classes/class_font.rst @@ -281,10 +281,20 @@ Returns the size of a bounding box of a single-line string, taking kerning and a For example, to get the string size as displayed by a single-line Label, use: -:: + +.. tabs:: + + .. code-tab:: gdscript var string_size = $Label.get_theme_font("font").get_string_size($Label.text, HORIZONTAL_ALIGNMENT_LEFT, -1, $Label.get_theme_font_size("font_size")) + .. code-tab:: csharp + + Label label = GetNode