diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index b4c42ad5e..c5cc9387f 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -646,7 +646,7 @@ Returns a reference to the specified function ``funcname`` in the ``instance`` n - :ref:`Array` **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`. :: @@ -665,6 +665,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. + ---- .. _class_@GDScript_method_hash: @@ -1084,7 +1086,7 @@ Output in the console would look something like this: - void **print_stack** **(** **)** -Prints a stack track at 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: @@ -1092,6 +1094,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. + ---- .. _class_@GDScript_method_printerr: diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 086866b99..02dac8d2f 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -1944,6 +1944,36 @@ Since :ref:`OK` has value 0, and all other failu .. _class_@GlobalScope_constant_PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS: +.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_ID: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_TYPE_STRING: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_VARIANT_TYPE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_BASE_TYPE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_INSTANCE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_SCRIPT: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_VARIANT_TYPE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_BASE_TYPE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_INSTANCE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_SCRIPT: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_TOO_BIG: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_VALID_TYPES: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_SAVE_FILE: + +.. _class_@GlobalScope_constant_PROPERTY_HINT_MAX: + enum **PropertyHint**: - **PROPERTY_HINT_NONE** = **0** --- No hint for the edited property. @@ -2000,6 +2030,45 @@ Unlike :ref:`PROPERTY_HINT_ENUM` - **PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS** = **24** --- Hints that an image is compressed using lossless compression. +- **PROPERTY_HINT_OBJECT_ID** = **25** + +- **PROPERTY_HINT_TYPE_STRING** = **26** --- Hint that a property represents a particular type. If a property is :ref:`TYPE_STRING`, allows to set a type from the create dialog. If you need to create an :ref:`Array` to contain elements of a specific type, the ``hint_string`` must encode nested types using ``":"`` and ``"/"`` for specifying :ref:`Resource` types. For instance: + +:: + + hint_string = "%s:" % [TYPE_INT] # Array of inteters. + hint_string = "%s:%s:" % [TYPE_ARRAY, TYPE_REAL] # Two-dimensional array of floats. + hint_string = "%s/%s:Resource" % [TYPE_OBJECT, TYPE_OBJECT] # Array of resources. + hint_string = "%s:%s/%s:Resource" % [TYPE_ARRAY, TYPE_OBJECT, TYPE_OBJECT] # Two-dimensional array of resources. + +\ **Note:** The final colon is required to specify for properly detecting built-in types. + +- **PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE** = **27** + +- **PROPERTY_HINT_METHOD_OF_VARIANT_TYPE** = **28** + +- **PROPERTY_HINT_METHOD_OF_BASE_TYPE** = **29** + +- **PROPERTY_HINT_METHOD_OF_INSTANCE** = **30** + +- **PROPERTY_HINT_METHOD_OF_SCRIPT** = **31** + +- **PROPERTY_HINT_PROPERTY_OF_VARIANT_TYPE** = **32** + +- **PROPERTY_HINT_PROPERTY_OF_BASE_TYPE** = **33** + +- **PROPERTY_HINT_PROPERTY_OF_INSTANCE** = **34** + +- **PROPERTY_HINT_PROPERTY_OF_SCRIPT** = **35** + +- **PROPERTY_HINT_OBJECT_TOO_BIG** = **36** + +- **PROPERTY_HINT_NODE_PATH_VALID_TYPES** = **37** + +- **PROPERTY_HINT_SAVE_FILE** = **38** + +- **PROPERTY_HINT_MAX** = **40** + ---- .. _enum_@GlobalScope_PropertyUsageFlags: diff --git a/classes/class_array.rst b/classes/class_array.rst index 4c92200c2..1464b5378 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -308,6 +308,8 @@ Assigns the given value to all elements in the array. This can typically be used array.resize(10) array.fill(0) # Initialize the 10 elements to 0. +\ **Note:** If ``value`` is of a reference type (:ref:`Object`-derived, ``Array``, :ref:`Dictionary`, etc.) then the array is filled with the references to the same object, i.e. no duplicates are created. + ---- .. _class_Array_method_find: @@ -509,6 +511,8 @@ Duplicates the subset described in the function and returns it in an array, deep 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: :: @@ -527,7 +531,9 @@ Sorts the array using a custom method. The arguments are an object that holds th For two elements ``a`` and ``b``, if the given method returns ``true``, element ``b`` will be after element ``a`` in the array. -\ **Note:** You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior. +\ **Note:** The sorting algorithm used is not `stable `__. 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. :: diff --git a/classes/class_audiostreamgeneratorplayback.rst b/classes/class_audiostreamgeneratorplayback.rst index f3cd54254..5271579a4 100644 --- a/classes/class_audiostreamgeneratorplayback.rst +++ b/classes/class_audiostreamgeneratorplayback.rst @@ -66,7 +66,7 @@ Clears the audio sample data buffer. - :ref:`int` **get_frames_available** **(** **)** |const| -Returns the number of audio data frames left to play. If this returned number reaches ``0``, the audio will stop playing until frames are added again. Therefore, make sure your script can always generate and push new audio frames fast enough to avoid audio cracking. +Returns the number of frames that can be pushed to the audio sample data buffer without overflowing it. If the result is ``0``, the buffer is full. ---- diff --git a/classes/class_backbuffercopy.rst b/classes/class_backbuffercopy.rst index 05c127709..89d7f3aa3 100644 --- a/classes/class_backbuffercopy.rst +++ b/classes/class_backbuffercopy.rst @@ -17,9 +17,9 @@ Copies a region of the screen (or the whole screen) to a buffer so it can be acc Description ----------- -Node for back-buffering the currently-displayed screen. The region defined in the BackBufferCopy node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer. +Node for back-buffering the currently-displayed screen. The region defined in the ``BackBufferCopy`` node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer. -\ **Note:** Since this node inherits from :ref:`Node2D` (and not :ref:`Control`), anchors and margins won't apply to child :ref:`Control`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control`-derived nodes as *siblings* to the BackBufferCopy node instead of adding them as children. +\ **Note:** Since this node inherits from :ref:`Node2D` (and not :ref:`Control`), anchors and margins won't apply to child :ref:`Control`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control`-derived nodes as *siblings* to the ``BackBufferCopy`` node instead of adding them as children. Properties ---------- @@ -43,11 +43,11 @@ Enumerations enum **CopyMode**: -- **COPY_MODE_DISABLED** = **0** --- Disables the buffering mode. This means the BackBufferCopy node will directly use the portion of screen it covers. +- **COPY_MODE_DISABLED** = **0** --- Disables the buffering mode. This means the ``BackBufferCopy`` node will directly use the portion of screen it covers. -- **COPY_MODE_RECT** = **1** --- BackBufferCopy buffers a rectangular region. +- **COPY_MODE_RECT** = **1** --- ``BackBufferCopy`` buffers a rectangular region. -- **COPY_MODE_VIEWPORT** = **2** --- BackBufferCopy buffers the entire screen. +- **COPY_MODE_VIEWPORT** = **2** --- ``BackBufferCopy`` buffers the entire screen. Property Descriptions --------------------- @@ -80,7 +80,7 @@ Buffer mode. See :ref:`CopyMode` constants. | *Getter* | get_rect() | +-----------+-----------------------------------+ -The area covered by the BackBufferCopy. Only used if :ref:`copy_mode` is :ref:`COPY_MODE_RECT`. +The area covered by the ``BackBufferCopy``. Only used if :ref:`copy_mode` is :ref:`COPY_MODE_RECT`. .. |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_cylindershape.rst b/classes/class_cylindershape.rst index 99d648979..483197997 100644 --- a/classes/class_cylindershape.rst +++ b/classes/class_cylindershape.rst @@ -19,6 +19,8 @@ Description Cylinder shape for collisions. +\ **Note:** When using GodotPhysics instead of the default Bullet physics engine, there are several known bugs with cylinder collision shapes. Using :ref:`CapsuleShape` or :ref:`BoxShape` instead is recommended. + Tutorials --------- diff --git a/classes/class_editorscript.rst b/classes/class_editorscript.rst index 3cbc211b3..5f20f4e1c 100644 --- a/classes/class_editorscript.rst +++ b/classes/class_editorscript.rst @@ -33,6 +33,8 @@ Scripts extending this class and implementing its :ref:`_run` displayed for clear areas of the scene. Only effec | *Getter* | get_bg_energy() | +-----------+----------------------+ -The power of the light emitted by the background. +The power of the light emitted by the background. This affects the sky brightness, the ambient light (if :ref:`ambient_light_sky_contribution` is greater than ``0.0``) and specular light from the sky. ---- diff --git a/classes/class_input.rst b/classes/class_input.rst index 7a5cb4364..07bd0793a 100644 --- a/classes/class_input.rst +++ b/classes/class_input.rst @@ -647,6 +647,8 @@ Sets a custom mouse cursor image, which is only visible inside the game window. \ **Note:** Only images imported with the **Lossless**, **Lossy** or **Uncompressed** compression modes are supported. The **Video RAM** compression mode can't be used for custom cursors. +\ **Note:** On the web platform, the maximum allowed cursor image size is 128×128. Cursor images larger than 32×32 will also only be displayed if the mouse cursor image is entirely located within the page for `security reasons `__. + ---- .. _class_Input_method_set_default_cursor_shape: diff --git a/classes/class_light.rst b/classes/class_light.rst index 9f14dfadb..fb5ffebdd 100644 --- a/classes/class_light.rst +++ b/classes/class_light.rst @@ -296,6 +296,8 @@ If ``true``, the light's effect is reversed, darkening areas and casting bright The size of the light in Godot units. Only considered in baked lightmaps and only if :ref:`light_bake_mode` is set to :ref:`BAKE_ALL`. Increasing this value will make the shadows appear blurrier. This can be used to simulate area lights to an extent. +\ **Note:** :ref:`light_size` is not affected by :ref:`Spatial.scale` (the light's scale or its parent's scale). + ---- .. _class_Light_property_light_specular: diff --git a/classes/class_navigationagent.rst b/classes/class_navigationagent.rst index 24f4c5fad..e4393058d 100644 --- a/classes/class_navigationagent.rst +++ b/classes/class_navigationagent.rst @@ -21,6 +21,8 @@ Description \ **Note:** After :ref:`set_target_location` is used it is required to use the :ref:`get_next_location` function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node. +\ **Note:** By default, the expensive calculations for avoidance are done in a thread. In HTML5 exports without thread support, they will be done on the main thread, which can lead to performance issues. + Properties ---------- diff --git a/classes/class_navigationagent2d.rst b/classes/class_navigationagent2d.rst index cfeae6757..aeb00de97 100644 --- a/classes/class_navigationagent2d.rst +++ b/classes/class_navigationagent2d.rst @@ -21,6 +21,8 @@ Description \ **Note:** After :ref:`set_target_location` is used it is required to use the :ref:`get_next_location` function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node. +\ **Note:** By default, the expensive calculations for avoidance are done in a thread. In HTML5 exports without thread support, they will be done on the main thread, which can lead to performance issues. + Properties ---------- diff --git a/classes/class_navigationserver.rst b/classes/class_navigationserver.rst index a51777c44..d15b63f94 100644 --- a/classes/class_navigationserver.rst +++ b/classes/class_navigationserver.rst @@ -29,6 +29,8 @@ To use the collision avoidance system, you may use agents. You can set an agent' \ **Note:** The collision avoidance system ignores regions. Using the modified velocity as-is might lead to pushing and agent outside of a navigable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine. +\ **Note:** By default, the expensive calculations for avoidance are done in a thread. In HTML5 exports without thread support, they will be done on the main thread, which can lead to performance issues. + This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying. Tutorials diff --git a/classes/class_omnilight.rst b/classes/class_omnilight.rst index be63c6039..d54453f33 100644 --- a/classes/class_omnilight.rst +++ b/classes/class_omnilight.rst @@ -101,6 +101,8 @@ The light's attenuation (drop-off) curve. A number of presets are available in t The light's radius. Note that the effectively lit area may appear to be smaller depending on the :ref:`omni_attenuation` in use. No matter the :ref:`omni_attenuation` in use, the light will never reach anything outside this radius. +\ **Note:** :ref:`omni_range` is not affected by :ref:`Spatial.scale` (the light's scale or its parent's scale). + ---- .. _class_OmniLight_property_omni_shadow_detail: diff --git a/classes/class_os.rst b/classes/class_os.rst index 9cb7e9c79..225623df5 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -1106,7 +1106,7 @@ Returns the audio driver name for the given index. - :ref:`String` **get_cache_dir** **(** **)** |const| -Returns the *global* cache data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the ``XDG_CACHE_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_config_dir` and :ref:`get_data_dir`. +Returns the *global* cache data directory according to the operating system's standards. On Linux, this path can be overridden by setting the ``XDG_CACHE_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_config_dir` and :ref:`get_data_dir`. Not to be confused with :ref:`get_user_data_dir`, which returns the *project-specific* user data path. @@ -1144,7 +1144,7 @@ Here's a minimal example on how to parse command-line arguments into a dictionar - :ref:`String` **get_config_dir** **(** **)** |const| -Returns the *global* user configuration directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the ``XDG_CONFIG_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_data_dir`. +Returns the *global* user configuration directory according to the operating system's standards. On Linux, this path can be overridden by setting the ``XDG_CONFIG_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_data_dir`. Not to be confused with :ref:`get_user_data_dir`, which returns the *project-specific* user data path. @@ -1174,7 +1174,7 @@ Returns the currently used video driver, using one of the values from :ref:`Vide - :ref:`String` **get_data_dir** **(** **)** |const| -Returns the *global* user data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the ``XDG_DATA_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_config_dir`. +Returns the *global* user data directory according to the operating system's standards. On Linux, this path can be overridden by setting the ``XDG_DATA_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir` and :ref:`get_config_dir`. Not to be confused with :ref:`get_user_data_dir`, which returns the *project-specific* user data path. @@ -2255,6 +2255,8 @@ Requests the OS to open a resource with the most appropriate program. For exampl Use :ref:`ProjectSettings.globalize_path` to convert a ``res://`` or ``user://`` path into a system path for use with this method. +\ **Note:** Use :ref:`String.percent_encode` to encode characters within URLs in a URL-safe, portable way. This is especially required for line breaks. Otherwise, :ref:`shell_open` may not work correctly in a project exported to the Web platform. + \ **Note:** This method is implemented on Android, iOS, HTML5, Linux, macOS and Windows. ---- diff --git a/classes/class_particles2d.rst b/classes/class_particles2d.rst index 3d5f04bb2..2896ef452 100644 --- a/classes/class_particles2d.rst +++ b/classes/class_particles2d.rst @@ -34,7 +34,9 @@ Tutorials - :doc:`Particle systems (2D) <../tutorials/2d/particle_systems_2d>` -- `2D Dodge The Creeps Demo `__ +- `2D Particles Demo `__ + +- `2D Dodge The Creeps Demo (uses GPUParticles2D for the trail behind the player) `__ Properties ---------- diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 25be776c2..d3090ba97 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -6720,12 +6720,16 @@ If set to a value greater than ``0.0``, contrast-adaptive sharpening will be app | *Default* | ``false`` | +-----------+-----------+ -If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. +If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode` is :ref:`Environment.BG_CANVAS`. In this case, :ref:`rendering/quality/intended_usage/framebuffer_allocation` must also be set to **3D**. + +In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. \ **Note:** Only available on the GLES3 backend. :ref:`rendering/quality/depth/hdr` must also be ``true`` for debanding to be effective. \ **Note:** There are known issues with debanding breaking rendering on mobile platforms. Due to this, it is recommended to leave this option disabled when targeting mobile platforms. +\ **Note:** This property is only read when the project starts. To set debanding at run-time, set :ref:`Viewport.debanding` on the root :ref:`Viewport` instead. + ---- .. _class_ProjectSettings_property_rendering/quality/filters/use_fxaa: diff --git a/classes/class_regex.rst b/classes/class_regex.rst index acbe95aa7..1bd730401 100644 --- a/classes/class_regex.rst +++ b/classes/class_regex.rst @@ -151,7 +151,9 @@ Returns whether this object has a valid search pattern assigned. - :ref:`RegExMatch` **search** **(** :ref:`String` subject, :ref:`int` offset=0, :ref:`int` end=-1 **)** |const| -Searches the text for the compiled pattern. Returns a :ref:`RegExMatch` container of the first matching result if found, otherwise ``null``. The region to search within can be specified without modifying where the start and end anchor would be. +Searches the text for the compiled pattern. Returns a :ref:`RegExMatch` container of the first matching result if found, otherwise ``null``. + +The region to search within can be specified with ``offset`` and ``end``. This is useful when searching for another match in the same ``subject`` by calling this method again after a previous success. Setting these parameters differs from passing over a shortened string. For example, the start anchor ``^`` is not affected by ``offset``, and the character before ``offset`` will be checked for the word boundary ``\b``. ---- @@ -159,7 +161,9 @@ Searches the text for the compiled pattern. Returns a :ref:`RegExMatch` **search_all** **(** :ref:`String` subject, :ref:`int` offset=0, :ref:`int` end=-1 **)** |const| -Searches the text for the compiled pattern. Returns an array of :ref:`RegExMatch` containers for each non-overlapping result. If no results were found, an empty array is returned instead. The region to search within can be specified without modifying where the start and end anchor would be. +Searches the text for the compiled pattern. Returns an array of :ref:`RegExMatch` containers for each non-overlapping result. If no results were found, an empty array is returned instead. + +The region to search within can be specified with ``offset`` and ``end``. This is useful when searching for another match in the same ``subject`` by calling this method again after a previous success. Setting these parameters differs from passing over a shortened string. For example, the start anchor ``^`` is not affected by ``offset``, and the character before ``offset`` will be checked for the word boundary ``\b``. ---- @@ -167,7 +171,9 @@ Searches the text for the compiled pattern. Returns an array of :ref:`RegExMatch - :ref:`String` **sub** **(** :ref:`String` subject, :ref:`String` replacement, :ref:`bool` all=false, :ref:`int` offset=0, :ref:`int` end=-1 **)** |const| -Searches the text for the compiled pattern and replaces it with the specified string. Escapes and backreferences such as ``$1`` and ``$name`` are expanded and resolved. By default, only the first instance is replaced, but it can be changed for all instances (global replacement). The region to search within can be specified without modifying where the start and end anchor would be. +Searches the text for the compiled pattern and replaces it with the specified string. Escapes and backreferences such as ``$1`` and ``$name`` are expanded and resolved. By default, only the first instance is replaced, but it can be changed for all instances (global replacement). + +The region to search within can be specified with ``offset`` and ``end``. This is useful when searching for another match in the same ``subject`` by calling this method again after a previous success. Setting these parameters differs from passing over a shortened string. For example, the start anchor ``^`` is not affected by ``offset``, and the character before ``offset`` will be checked for the word boundary ``\b``. .. |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_scenetree.rst b/classes/class_scenetree.rst index 28d36cf68..4ff72efb2 100644 --- a/classes/class_scenetree.rst +++ b/classes/class_scenetree.rst @@ -264,6 +264,8 @@ enum **GroupCallFlags**: - **GROUP_CALL_UNIQUE** = **4** --- Call a group only once even if the call is executed many times. +\ **Note:** Arguments are not taken into account when deciding whether the call is unique or not. Therefore when the same method is called with different arguments, only the first call will be performed. + ---- .. _enum_SceneTree_StretchMode: diff --git a/classes/class_spatial.rst b/classes/class_spatial.rst index 9776861d8..3881074c7 100644 --- a/classes/class_spatial.rst +++ b/classes/class_spatial.rst @@ -293,6 +293,8 @@ Scale part of the local transformation. \ **Note:** Mixed negative scales in 3D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Godot, the scale values will either be all positive or all negative. +\ **Note:** Not all nodes are visually scaled by the :ref:`scale` property. For example, :ref:`Light`\ s are not visually affected by :ref:`scale`. + ---- .. _class_Spatial_property_transform: diff --git a/classes/class_spotlight.rst b/classes/class_spotlight.rst index 7275e91f7..828451b9a 100644 --- a/classes/class_spotlight.rst +++ b/classes/class_spotlight.rst @@ -58,6 +58,8 @@ Property Descriptions The spotlight's angle in degrees. +\ **Note:** :ref:`spot_angle` is not affected by :ref:`Spatial.scale` (the light's scale or its parent's scale). + ---- .. _class_SpotLight_property_spot_angle_attenuation: @@ -106,6 +108,8 @@ The spotlight's light energy attenuation curve. The maximal range that can be reached by the spotlight. Note that the effectively lit area may appear to be smaller depending on the :ref:`spot_attenuation` in use. No matter the :ref:`spot_attenuation` in use, the light will never reach anything outside this range. +\ **Note:** :ref:`spot_range` is not affected by :ref:`Spatial.scale` (the light's scale or its parent's scale). + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_string.rst b/classes/class_string.rst index 2aaf56ae4..7ec394010 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -867,7 +867,7 @@ Returns a copy of the string with characters removed from the left. The ``chars` - :ref:`bool` **match** **(** :ref:`String` expr **)** -Does a simple case-sensitive expression match, where ``"*"`` matches zero or more arbitrary characters and ``"?"`` matches any single character except a period (``"."``). An empty string or empty expression always evaluates to ``false``. +Does a simple expression match (also called "glob" or "globbing"), where ``*`` matches zero or more arbitrary characters and ``?`` matches any single character except a period (``.``). An empty string or empty expression always evaluates to ``false``. ---- @@ -875,7 +875,7 @@ Does a simple case-sensitive expression match, where ``"*"`` matches zero or mor - :ref:`bool` **matchn** **(** :ref:`String` expr **)** -Does a simple case-insensitive expression match, where ``"*"`` matches zero or more arbitrary characters and ``"?"`` matches any single character except a period (``"."``). An empty string or empty expression always evaluates to ``false``. +Does a simple **case-insensitive** expression match, where ``*`` matches zero or more arbitrary characters and ``?`` matches any single character except a period (``.``). An empty string or empty expression always evaluates to ``false``. ---- @@ -953,7 +953,7 @@ Formats a number to have an exact number of ``digits`` before the decimal point. - :ref:`String` **percent_decode** **(** **)** -Decode a percent-encoded string. See :ref:`percent_encode`. +Decode a percent-encoded string (also called URI-encoded string). See also :ref:`percent_encode`. ---- @@ -961,7 +961,7 @@ Decode a percent-encoded string. See :ref:`percent_encode` **percent_encode** **(** **)** -Percent-encodes a string. Encodes parameters in a URL when sending a HTTP GET request (and bodies of form-urlencoded POST requests). +Percent-encodes a string (also called URI-encoded string). Encodes parameters in a URL when sending a HTTP GET request (and bodies of form-urlencoded POST requests). See also :ref:`percent_decode`. ---- diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index 2fc0dfd50..1bef7f82b 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -21,7 +21,7 @@ A Viewport creates a different view into the screen, or a sub-view inside anothe Optionally, a viewport can have its own 2D or 3D world, so they don't share what they draw with other viewports. -If a viewport is a child of a :ref:`ViewportContainer`, it will automatically take up its size, otherwise it must be set manually. +If a viewport is a child of a :ref:`ViewportContainer`, the viewport will automatically take up the container's size, otherwise it must be set manually. Viewports can also choose to be audio listeners, so they generate positional audio depending on a 2D or 3D camera child of it. @@ -465,7 +465,9 @@ The canvas transform of the viewport, useful for changing the on-screen position | *Getter* | get_use_debanding() | +-----------+--------------------------+ -If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. +If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode` is :ref:`Environment.BG_CANVAS`. In this case, :ref:`usage` must also be set to :ref:`USAGE_3D`. See also :ref:`ProjectSettings.rendering/quality/filters/use_debanding`. + +In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. \ **Note:** Only available on the GLES3 backend. :ref:`hdr` must also be ``true`` for debanding to be effective. @@ -499,7 +501,7 @@ The overlay mode for test rendered geometry in debug purposes. | *Getter* | is_3d_disabled() | +-----------+-----------------------+ -If ``true``, the viewport will disable 3D rendering. For actual disabling use ``usage``. +If ``true``, the viewport will disable 3D rendering. To actually disable allocation of 3D buffers, set :ref:`usage` instead. ---- @@ -887,7 +889,7 @@ If ``true``, the viewport should render its background as transparent. | *Getter* | get_usage() | +-----------+------------------+ -The rendering mode of viewport. +The viewport's rendering mode. This controls which buffers are allocated for the viewport (2D only, or 2D + 3D). 2D-only options can reduce memory usage and improve performance slightly, especially on low-end devices. \ **Note:** If set to :ref:`USAGE_2D` or :ref:`USAGE_2D_NO_SAMPLING`, :ref:`hdr` will have no effect when enabled since HDR is not supported for 2D. diff --git a/classes/class_viewportcontainer.rst b/classes/class_viewportcontainer.rst index 660b0e39a..3c073685d 100644 --- a/classes/class_viewportcontainer.rst +++ b/classes/class_viewportcontainer.rst @@ -17,7 +17,7 @@ Control for holding :ref:`Viewport`\ s. Description ----------- -A :ref:`Container` node that holds a :ref:`Viewport`, automatically setting its size. +A :ref:`Container` node that holds a :ref:`Viewport`, automatically setting the viewport's size. \ **Note:** Changing a ViewportContainer's :ref:`Control.rect_scale` will cause its contents to appear distorted. To change its visual size without causing distortion, adjust the node's margins instead (if it's not already in a container). diff --git a/classes/class_visualinstance.rst b/classes/class_visualinstance.rst index c5e282859..f15f2c689 100644 --- a/classes/class_visualinstance.rst +++ b/classes/class_visualinstance.rst @@ -24,9 +24,13 @@ The ``VisualInstance`` is used to connect a resource to a visual representation. Properties ---------- -+-----------------------+-----------------------------------------------------+-------+ -| :ref:`int` | :ref:`layers` | ``1`` | -+-----------------------+-----------------------------------------------------+-------+ ++---------------------------+---------------------------------------------------------------------------------------+----------+ +| :ref:`int` | :ref:`layers` | ``1`` | ++---------------------------+---------------------------------------------------------------------------------------+----------+ +| :ref:`float` | :ref:`sorting_offset` | ``0.0`` | ++---------------------------+---------------------------------------------------------------------------------------+----------+ +| :ref:`bool` | :ref:`sorting_use_aabb_center` | ``true`` | ++---------------------------+---------------------------------------------------------------------------------------+----------+ Methods ------- @@ -66,6 +70,40 @@ The render layer(s) this ``VisualInstance`` is drawn on. This object will only be visible for :ref:`Camera`\ s whose cull mask includes the render object this ``VisualInstance`` is set to. +---- + +.. _class_VisualInstance_property_sorting_offset: + +- :ref:`float` **sorting_offset** + ++-----------+---------------------------+ +| *Default* | ``0.0`` | ++-----------+---------------------------+ +| *Setter* | set_sorting_offset(value) | ++-----------+---------------------------+ +| *Getter* | get_sorting_offset() | ++-----------+---------------------------+ + +The sorting offset used by this ``VisualInstance``. Adjusting it to a higher value will make the ``VisualInstance`` reliably draw on top of other ``VisualInstance``\ s that are otherwise positioned at the same spot. + +---- + +.. _class_VisualInstance_property_sorting_use_aabb_center: + +- :ref:`bool` **sorting_use_aabb_center** + ++-----------+------------------------------------+ +| *Default* | ``true`` | ++-----------+------------------------------------+ +| *Setter* | set_sorting_use_aabb_center(value) | ++-----------+------------------------------------+ +| *Getter* | is_sorting_use_aabb_center() | ++-----------+------------------------------------+ + +If ``true``, the object is sorted based on the :ref:`AABB` center. Sorted based on the global position otherwise. + +The :ref:`AABB` center based sorting is generally more accurate for 3D models. The position based sorting instead allows to better control the drawing order when working with :ref:`Particles` and :ref:`CPUParticles`. + Method Descriptions -------------------