diff options
Diffstat (limited to 'doc')
31 files changed, 339 insertions, 110 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index dce96fb315..18ea29857b 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -2419,63 +2419,66 @@ <constant name="PROPERTY_HINT_LENGTH" value="5" enum="PropertyHint"> Deprecated hint, unused. </constant> - <constant name="PROPERTY_HINT_KEY_ACCEL" value="6" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LINK" value="6" enum="PropertyHint"> + Hints that a vector property should allow linking values (e.g. to edit both [code]x[/code] and [code]y[/code] together). + </constant> + <constant name="PROPERTY_HINT_KEY_ACCEL" value="7" enum="PropertyHint"> Deprecated hint, unused. </constant> - <constant name="PROPERTY_HINT_FLAGS" value="7" enum="PropertyHint"> + <constant name="PROPERTY_HINT_FLAGS" value="8" enum="PropertyHint"> Hints that an integer property is a bitmask with named bit flags. For example, to allow toggling bits 0, 1, 2 and 4, the hint could be something like [code]"Bit0,Bit1,Bit2,,Bit4"[/code]. </constant> - <constant name="PROPERTY_HINT_LAYERS_2D_RENDER" value="8" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LAYERS_2D_RENDER" value="9" enum="PropertyHint"> Hints that an integer property is a bitmask using the optionally named 2D render layers. </constant> - <constant name="PROPERTY_HINT_LAYERS_2D_PHYSICS" value="9" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LAYERS_2D_PHYSICS" value="10" enum="PropertyHint"> Hints that an integer property is a bitmask using the optionally named 2D physics layers. </constant> - <constant name="PROPERTY_HINT_LAYERS_2D_NAVIGATION" value="10" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LAYERS_2D_NAVIGATION" value="11" enum="PropertyHint"> Hints that an integer property is a bitmask using the optionally named 2D navigation layers. </constant> - <constant name="PROPERTY_HINT_LAYERS_3D_RENDER" value="11" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LAYERS_3D_RENDER" value="12" enum="PropertyHint"> Hints that an integer property is a bitmask using the optionally named 3D render layers. </constant> - <constant name="PROPERTY_HINT_LAYERS_3D_PHYSICS" value="12" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LAYERS_3D_PHYSICS" value="13" enum="PropertyHint"> Hints that an integer property is a bitmask using the optionally named 3D physics layers. </constant> - <constant name="PROPERTY_HINT_LAYERS_3D_NAVIGATION" value="13" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LAYERS_3D_NAVIGATION" value="14" enum="PropertyHint"> Hints that an integer property is a bitmask using the optionally named 2D navigation layers. </constant> - <constant name="PROPERTY_HINT_FILE" value="14" enum="PropertyHint"> + <constant name="PROPERTY_HINT_FILE" value="15" enum="PropertyHint"> Hints that a string property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. </constant> - <constant name="PROPERTY_HINT_DIR" value="15" enum="PropertyHint"> + <constant name="PROPERTY_HINT_DIR" value="16" enum="PropertyHint"> Hints that a string property is a path to a directory. Editing it will show a file dialog for picking the path. </constant> - <constant name="PROPERTY_HINT_GLOBAL_FILE" value="16" enum="PropertyHint"> + <constant name="PROPERTY_HINT_GLOBAL_FILE" value="17" enum="PropertyHint"> Hints that a string property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. </constant> - <constant name="PROPERTY_HINT_GLOBAL_DIR" value="17" enum="PropertyHint"> + <constant name="PROPERTY_HINT_GLOBAL_DIR" value="18" enum="PropertyHint"> Hints that a string property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path. </constant> - <constant name="PROPERTY_HINT_RESOURCE_TYPE" value="18" enum="PropertyHint"> + <constant name="PROPERTY_HINT_RESOURCE_TYPE" value="19" enum="PropertyHint"> Hints that a property is an instance of a [Resource]-derived type, optionally specified via the hint string (e.g. [code]"Texture2D"[/code]). Editing it will show a popup menu of valid resource types to instantiate. </constant> - <constant name="PROPERTY_HINT_MULTILINE_TEXT" value="19" enum="PropertyHint"> + <constant name="PROPERTY_HINT_MULTILINE_TEXT" value="20" enum="PropertyHint"> Hints that a string property is text with line breaks. Editing it will show a text input field where line breaks can be typed. </constant> - <constant name="PROPERTY_HINT_PLACEHOLDER_TEXT" value="20" enum="PropertyHint"> + <constant name="PROPERTY_HINT_PLACEHOLDER_TEXT" value="21" enum="PropertyHint"> Hints that a string property should have a placeholder text visible on its input field, whenever the property is empty. The hint string is the placeholder text to use. </constant> - <constant name="PROPERTY_HINT_COLOR_NO_ALPHA" value="21" enum="PropertyHint"> + <constant name="PROPERTY_HINT_COLOR_NO_ALPHA" value="22" enum="PropertyHint"> Hints that a color property should be edited without changing its alpha component, i.e. only R, G and B channels are edited. </constant> - <constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSY" value="22" enum="PropertyHint"> + <constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSY" value="23" enum="PropertyHint"> Hints that an image is compressed using lossy compression. </constant> - <constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS" value="23" enum="PropertyHint"> + <constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS" value="24" enum="PropertyHint"> Hints that an image is compressed using lossless compression. </constant> - <constant name="PROPERTY_HINT_OBJECT_ID" value="24" enum="PropertyHint"> + <constant name="PROPERTY_HINT_OBJECT_ID" value="25" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_TYPE_STRING" value="25" enum="PropertyHint"> + <constant name="PROPERTY_HINT_TYPE_STRING" value="26" enum="PropertyHint"> Hint that a property represents a particular type. If a property is [constant TYPE_STRING], allows to set a type from the create dialog. If you need to create an [Array] to contain elements of a specific type, the [code]hint_string[/code] must encode nested types using [code]":"[/code] and [code]"/"[/code] for specifying [Resource] types. For instance: [codeblock] hint_string = "%s:" % [TYPE_INT] # Array of inteters. @@ -2485,43 +2488,43 @@ [/codeblock] [b]Note:[/b] The final colon is required to specify for properly detecting built-in types. </constant> - <constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="26" enum="PropertyHint"> + <constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="27" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_METHOD_OF_VARIANT_TYPE" value="27" enum="PropertyHint"> + <constant name="PROPERTY_HINT_METHOD_OF_VARIANT_TYPE" value="28" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_METHOD_OF_BASE_TYPE" value="28" enum="PropertyHint"> + <constant name="PROPERTY_HINT_METHOD_OF_BASE_TYPE" value="29" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_METHOD_OF_INSTANCE" value="29" enum="PropertyHint"> + <constant name="PROPERTY_HINT_METHOD_OF_INSTANCE" value="30" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_METHOD_OF_SCRIPT" value="30" enum="PropertyHint"> + <constant name="PROPERTY_HINT_METHOD_OF_SCRIPT" value="31" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_PROPERTY_OF_VARIANT_TYPE" value="31" enum="PropertyHint"> + <constant name="PROPERTY_HINT_PROPERTY_OF_VARIANT_TYPE" value="32" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_PROPERTY_OF_BASE_TYPE" value="32" enum="PropertyHint"> + <constant name="PROPERTY_HINT_PROPERTY_OF_BASE_TYPE" value="33" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_PROPERTY_OF_INSTANCE" value="33" enum="PropertyHint"> + <constant name="PROPERTY_HINT_PROPERTY_OF_INSTANCE" value="34" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_PROPERTY_OF_SCRIPT" value="34" enum="PropertyHint"> + <constant name="PROPERTY_HINT_PROPERTY_OF_SCRIPT" value="35" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_OBJECT_TOO_BIG" value="35" enum="PropertyHint"> + <constant name="PROPERTY_HINT_OBJECT_TOO_BIG" value="36" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_NODE_PATH_VALID_TYPES" value="36" enum="PropertyHint"> + <constant name="PROPERTY_HINT_NODE_PATH_VALID_TYPES" value="37" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_SAVE_FILE" value="37" enum="PropertyHint"> + <constant name="PROPERTY_HINT_SAVE_FILE" value="38" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="38" enum="PropertyHint"> + <constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="39" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_INT_IS_POINTER" value="40" enum="PropertyHint"> + <constant name="PROPERTY_HINT_INT_IS_POINTER" value="41" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_ARRAY_TYPE" value="39" enum="PropertyHint"> + <constant name="PROPERTY_HINT_ARRAY_TYPE" value="40" enum="PropertyHint"> </constant> - <constant name="PROPERTY_HINT_LOCALE_ID" value="41" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LOCALE_ID" value="42" enum="PropertyHint"> Hints that a string property is a locale code. Editing it will show a locale dialog for picking language and country. </constant> - <constant name="PROPERTY_HINT_LOCALIZABLE_STRING" value="42" enum="PropertyHint"> + <constant name="PROPERTY_HINT_LOCALIZABLE_STRING" value="43" enum="PropertyHint"> Hints that a dictionary property is string translation map. Dictionary keys are locale codes and, values are translated strings. </constant> - <constant name="PROPERTY_HINT_MAX" value="43" enum="PropertyHint"> + <constant name="PROPERTY_HINT_MAX" value="44" enum="PropertyHint"> </constant> <constant name="PROPERTY_USAGE_NONE" value="0" enum="PropertyUsageFlags"> </constant> diff --git a/doc/classes/AnimationLibrary.xml b/doc/classes/AnimationLibrary.xml index 0a731edadd..d856c65dfc 100644 --- a/doc/classes/AnimationLibrary.xml +++ b/doc/classes/AnimationLibrary.xml @@ -51,18 +51,18 @@ </members> <signals> <signal name="animation_added"> - <argument index="0" name="name" type="Animation" /> + <argument index="0" name="name" type="StringName" /> <description> </description> </signal> <signal name="animation_removed"> - <argument index="0" name="name" type="Animation" /> + <argument index="0" name="name" type="StringName" /> <description> </description> </signal> <signal name="animation_renamed"> - <argument index="0" name="name" type="Animation" /> - <argument index="1" name="to_name" type="Animation" /> + <argument index="0" name="name" type="StringName" /> + <argument index="1" name="to_name" type="StringName" /> <description> </description> </signal> diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index a9c6030809..d3ae85101d 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -359,6 +359,7 @@ </member> <member name="texture_filter" type="int" setter="set_texture_filter" getter="get_texture_filter" enum="BaseMaterial3D.TextureFilter" default="3"> Filter flags for the texture. See [enum TextureFilter] for options. + [b]Note:[/b] [member heightmap_texture] is always sampled with linear filtering, even if nearest-neighbor filtering is selected here. This is to ensure the heightmap effect looks as intended. If you need sharper height transitions between pixels, resize the heightmap texture in an image editor with nearest-neighbor filtering. </member> <member name="texture_repeat" type="bool" setter="set_flag" getter="get_flag" default="true"> Repeat flags for the texture. See [enum TextureFilter] for options. diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index d85d02fbfb..4ece57fa81 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -92,6 +92,9 @@ <member name="text_direction" type="int" setter="set_text_direction" getter="get_text_direction" enum="Control.TextDirection" default="0"> Base text writing direction. </member> + <member name="text_overrun_behavior" type="int" setter="set_text_overrun_behavior" getter="get_text_overrun_behavior" enum="TextParagraph.OverrunBehavior" default="0"> + Sets the clipping behavior when the text exceeds the node's bounding rectangle. See [enum TextParagraph.OverrunBehavior] for a description of all modes. + </member> </members> <theme_items> <theme_item name="font_color" data_type="color" type="Color" default="Color(0.875, 0.875, 0.875, 1)"> diff --git a/doc/classes/CurveTexture.xml b/doc/classes/CurveTexture.xml index 6aa39e453e..85473fc237 100644 --- a/doc/classes/CurveTexture.xml +++ b/doc/classes/CurveTexture.xml @@ -5,23 +5,27 @@ </brief_description> <description> Renders a given [Curve] provided to it. Simplifies the task of drawing curves and/or saving them as image files. + If you need to store up to 3 curves within a single texture, use [CurveXYZTexture] instead. See also [GradientTexture1D] and [GradientTexture2D]. </description> <tutorials> </tutorials> <members> <member name="curve" type="Curve" setter="set_curve" getter="get_curve"> - The [code]curve[/code] rendered onto the texture. + The [Curve] that is rendered onto the texture. </member> <member name="texture_mode" type="int" setter="set_texture_mode" getter="get_texture_mode" enum="CurveTexture.TextureMode" default="0"> + The format the texture should be generated with. When passing a CurveTexture as a input to a [Shader], this may need to be adjusted. </member> <member name="width" type="int" setter="set_width" getter="get_width" default="256"> - The width of the texture. + The width of the texture (in pixels). Higher values make it possible to represent high-frequency data better (such as sudden direction changes), at the cost of increased generation time and memory usage. </member> </members> <constants> <constant name="TEXTURE_MODE_RGB" value="0" enum="TextureMode"> + Store the curve equally across the red, green and blue channels. This uses more video memory, but is more compatible with shaders that only read the green and blue values. </constant> <constant name="TEXTURE_MODE_RED" value="1" enum="TextureMode"> + Store the curve only in the red channel. This saves video memory, but some custom shaders may not be able to work with this. </constant> </constants> </class> diff --git a/doc/classes/CurveXYZTexture.xml b/doc/classes/CurveXYZTexture.xml index d289e394aa..e3f2e8fc45 100644 --- a/doc/classes/CurveXYZTexture.xml +++ b/doc/classes/CurveXYZTexture.xml @@ -1,19 +1,26 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="CurveXYZTexture" inherits="Texture2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + A texture that shows 3 different curves (stored on the red, green and blue color channels). </brief_description> <description> + Renders 3 given [Curve]s provided to it, on the red, green and blue channels respectively. Compared to using separate [CurveTexture]s, this further simplifies the task of drawing curves and/or saving them as image files. + If you only need to store one curve within a single texture, use [CurveTexture] instead. See also [GradientTexture1D] and [GradientTexture2D]. </description> <tutorials> </tutorials> <members> <member name="curve_x" type="Curve" setter="set_curve_x" getter="get_curve_x"> + The [Curve] that is rendered onto the texture's red channel. </member> <member name="curve_y" type="Curve" setter="set_curve_y" getter="get_curve_y"> + The [Curve] that is rendered onto the texture's green channel. </member> <member name="curve_z" type="Curve" setter="set_curve_z" getter="get_curve_z"> + The [Curve] that is rendered onto the texture's blue channel. </member> <member name="width" type="int" setter="set_width" getter="get_width" default="256"> + The width of the texture (in pixels). Higher values make it possible to represent high-frequency data better (such as sudden direction changes), at the cost of increased generation time and memory usage. </member> </members> </class> diff --git a/doc/classes/FontData.xml b/doc/classes/FontData.xml index a423d7a4e4..d32e7b3a94 100644 --- a/doc/classes/FontData.xml +++ b/doc/classes/FontData.xml @@ -3,7 +3,7 @@ <brief_description> Font source data and prerendered glyph cache, imported from dynamic or bitmap font. Supported font formats: - - Dynamic font importer: TrueType (.ttf), OpenType (.otf), WOFF (.woff), WOFF2 (.woff2), Type 1 (.pfb, .pfm). + - Dynamic font importer: TrueType (.ttf), TrueType collection (.ttc), OpenType (.otf), OpenType collection (.otc), WOFF (.woff), WOFF2 (.woff2), Type 1 (.pfb, .pfm). - Bitmap font importer: AngelCode BMFont (.fnt, .font), text and binary (version 3) format variants. - Monospace image font importer: All supported image formats. </brief_description> @@ -87,6 +87,12 @@ Returns font descent (number of pixels below the baseline). </description> </method> + <method name="get_face_count" qualifiers="const"> + <return type="int" /> + <description> + Returns number of faces in the TrueType / OpenType collection. + </description> + </method> <method name="get_glyph_advance" qualifiers="const"> <return type="Vector2" /> <argument index="0" name="cache_index" type="int" /> @@ -318,7 +324,8 @@ <return type="int" enum="Error" /> <argument index="0" name="path" type="String" /> <description> - Loads a TrueType (.ttf), OpenType (.otf), WOFF (.woff), WOFF2 (.woff2) or Type 1 (.pfb, .pfm) dynamic font from file [code]path[/code]. + Loads a TrueType (.ttf), TrueType collection (.ttc), OpenType (.otf), OpenType collection (.otc), WOFF (.woff), WOFF2 (.woff2) or Type 1 (.pfb, .pfm) dynamic font from file [code]path[/code]. + [b]Note:[/b] Use [member face_index] to select specific face from the collection file. [b]Warning:[/b] This method should only be used in the editor or in cases when you need to load external fonts at run-time, such as fonts located at the [code]user://[/code] directory. </description> </method> @@ -570,6 +577,9 @@ <member name="embolden" type="float" setter="set_embolden" getter="get_embolden" default="0.0"> If is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness. </member> + <member name="face_index" type="int" setter="set_face_index" getter="get_face_index" default="0"> + Active face index in the TrueType / OpenType collection file. + </member> <member name="fixed_size" type="int" setter="set_fixed_size" getter="get_fixed_size" default="0"> Font size, used only for the bitmap fonts. </member> diff --git a/doc/classes/GradientTexture1D.xml b/doc/classes/GradientTexture1D.xml index a124753a9f..3254754ac1 100644 --- a/doc/classes/GradientTexture1D.xml +++ b/doc/classes/GradientTexture1D.xml @@ -4,7 +4,7 @@ Gradient-filled texture. </brief_description> <description> - GradientTexture1D uses a [Gradient] to fill the texture data. The gradient will be filled from left to right using colors obtained from the gradient. This means the texture does not necessarily represent an exact copy of the gradient, but instead an interpolation of samples obtained from the gradient at fixed steps (see [member width]). + GradientTexture1D uses a [Gradient] to fill the texture data. The gradient will be filled from left to right using colors obtained from the gradient. This means the texture does not necessarily represent an exact copy of the gradient, but instead an interpolation of samples obtained from the gradient at fixed steps (see [member width]). See also [GradientTexture2D], [CurveTexture] and [CurveXYZTexture]. </description> <tutorials> </tutorials> diff --git a/doc/classes/GradientTexture2D.xml b/doc/classes/GradientTexture2D.xml index 4362578932..7561f1b947 100644 --- a/doc/classes/GradientTexture2D.xml +++ b/doc/classes/GradientTexture2D.xml @@ -4,7 +4,7 @@ Gradient-filled 2D texture. </brief_description> <description> - The texture uses a [Gradient] to fill the texture data in 2D space. The gradient is filled according to the specified [member fill] and [member repeat] types using colors obtained from the gradient. The texture does not necessarily represent an exact copy of the gradient, but instead an interpolation of samples obtained from the gradient at fixed steps (see [member width] and [member height]). + The texture uses a [Gradient] to fill the texture data in 2D space. The gradient is filled according to the specified [member fill] and [member repeat] types using colors obtained from the gradient. The texture does not necessarily represent an exact copy of the gradient, but instead an interpolation of samples obtained from the gradient at fixed steps (see [member width] and [member height]). See also [GradientTexture1D], [CurveTexture] and [CurveXYZTexture]. </description> <tutorials> </tutorials> diff --git a/doc/classes/LightmapGI.xml b/doc/classes/LightmapGI.xml index ee98356962..ffde0d95ce 100644 --- a/doc/classes/LightmapGI.xml +++ b/doc/classes/LightmapGI.xml @@ -4,80 +4,122 @@ Computes and stores baked lightmaps for fast global illumination. </brief_description> <description> - The [LightmapGI] node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. [LightmapGI] can also provide rough reflections using spherical harmonics if [member directional] is enabled. Dynamic objects can receive indirect lighting thanks to [i]light probes[/i], which can be automatically placed by setting [member generate_probes_subdiv]. Additional lightmap probes can also be added by creating [LightmapProbe] nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a [LightmapGI] node is also slower compared to [VoxelGI]. + The [LightmapGI] node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. [LightmapGI] can also provide rough reflections using spherical harmonics if [member directional] is enabled. Dynamic objects can receive indirect lighting thanks to [i]light probes[/i], which can be automatically placed by setting [member generate_probes_subdiv] to a value other than [constant GENERATE_PROBES_DISABLED]. Additional lightmap probes can also be added by creating [LightmapProbe] nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a [LightmapGI] node is also slower compared to [VoxelGI]. [b]Procedural generation:[/b] Lightmap baking functionality is only available in the editor. This means [LightmapGI] is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use [VoxelGI] or SDFGI instead (see [member Environment.sdfgi_enabled]). [b]Performance:[/b] [LightmapGI] provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices. + [b]Note:[/b] Due to how lightmaps work, most properties only have a visible effect once lightmaps are baked again. + [b]Note:[/b] Lightmap baking on [CSGShape3D]s and [PrimitiveMesh]es is not supported, as these cannot store UV2 data required for baking. + [b]Note:[/b] If no custom lightmappers are installed, [LightmapGI] can only be baked when using the Vulkan backend (Clustered or Mobile), not OpenGL. </description> <tutorials> </tutorials> <members> <member name="bias" type="float" setter="set_bias" getter="get_bias" default="0.0005"> + The bias to use when computing shadows. Increasing [member bias] can fix shadow acne on the resulting baked lightmap, but can introduce peter-panning (shadows not connecting to their casters). Real-time [Light3D] shadows are not affected by this [member bias] property. </member> <member name="bounces" type="int" setter="set_bounces" getter="get_bounces" default="1"> + Number of light bounces that are taken into account during baking. Higher values result in brighter, more realistic lighting, at the cost of longer bake times. If set to [code]0[/code], only environment lighting, direct light and emissive lighting is baked. </member> <member name="directional" type="bool" setter="set_directional" getter="is_directional" default="false"> + If [code]true[/code], bakes lightmaps to contain directional information as spherical harmonics. This results in more realistic lighting appearance, especially with normal mapped materials and for lights that their have direct light baked ([member Light3D.light_bake_mode] set to [constant Light3D.BAKE_STATIC]). The directional information is also used to provide rough reflections for static and dynamic objects. This has a small run-time performance cost as the shader has to perform more work to interpret the direction information from the lightmap. Directional lightmaps also take longer to bake and result in larger file sizes. + [b]Note:[/b] The property's name has no relationship with [DirectionalLight3D]. [member directional] works with all light types. </member> <member name="environment_custom_color" type="Color" setter="set_environment_custom_color" getter="get_environment_custom_color"> + The color to use for environment lighting. Only effective if [member environment_mode] is [constant ENVIRONMENT_MODE_CUSTOM_COLOR]. </member> <member name="environment_custom_energy" type="float" setter="set_environment_custom_energy" getter="get_environment_custom_energy"> + The color multiplier to use for environment lighting. Only effective if [member environment_mode] is [constant ENVIRONMENT_MODE_CUSTOM_COLOR]. </member> <member name="environment_custom_sky" type="Sky" setter="set_environment_custom_sky" getter="get_environment_custom_sky"> + The sky to use as a source of environment lighting. Only effective if [member environment_mode] is [constant ENVIRONMENT_MODE_CUSTOM_SKY]. </member> <member name="environment_mode" type="int" setter="set_environment_mode" getter="get_environment_mode" enum="LightmapGI.EnvironmentMode" default="0"> + The environment mode to use when baking lightmaps. </member> <member name="generate_probes_subdiv" type="int" setter="set_generate_probes" getter="get_generate_probes" enum="LightmapGI.GenerateProbes" default="0"> + The level of subdivision to use when automatically generating [LightmapProbe]s for dynamic object lighting. Higher values result in more accurate indirect lighting on dynamic objects, at the cost of longer bake times and larger file sizes. + [b]Note:[/b] Automatically generated [LightmapProbe]s are not visible as nodes in the Scene tree dock, and cannot be modified this way after they are generated. + [b]Note:[/b] Regardless of [member generate_probes_subdiv], direct lighting on dynamic objects is always applied using [Light3D] nodes in real-time. </member> <member name="interior" type="bool" setter="set_interior" getter="is_interior" default="false"> + If [code]true[/code], ignore environment lighting when baking lightmaps. </member> <member name="light_data" type="LightmapGIData" setter="set_light_data" getter="get_light_data"> + The [LightmapGIData] associated to this [LightmapGI] node. This resource is automatically created after baking, and is not meant to be created manually. </member> <member name="max_texture_size" type="int" setter="set_max_texture_size" getter="get_max_texture_size" default="16384"> + The maximum texture size for the generated texture atlas. Higher values will result in fewer slices being generated, but may not work on all hardware as a result of hardware limitations on texture sizes. Leave [member max_texture_size] at its default value of [code]16384[/code] if unsure. </member> <member name="quality" type="int" setter="set_bake_quality" getter="get_bake_quality" enum="LightmapGI.BakeQuality" default="1"> + The quality preset to use when baking lightmaps. This affects bake times, but output file sizes remain mostly identical across quality levels. + To further speed up bake times, decrease [member bounces], disable [member use_denoiser] and increase the lightmap texel size on 3D scenes in the Import doc. </member> <member name="use_denoiser" type="bool" setter="set_use_denoiser" getter="is_using_denoiser" default="true"> + If [code]true[/code], uses a CPU-based denoising algorithm on the generated lightmap. This eliminates most noise within the generated lightmap at the cost of longer bake times. File sizes are generally not impacted significantly by the use of a denoiser, although lossless compression may do a better job at compressing a denoised image. + [b]Note:[/b] The built-in denoiser (OpenImageDenoise) may crash when denoising lightmaps in large scenes. If you encounter a crash at the end of lightmap baking, try disabling [member use_denoiser]. </member> </members> <constants> <constant name="BAKE_QUALITY_LOW" value="0" enum="BakeQuality"> + Low bake quality (fastest bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/low_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/low_quality_probe_ray_count]. </constant> <constant name="BAKE_QUALITY_MEDIUM" value="1" enum="BakeQuality"> + Medium bake quality (fast bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/medium_quality_probe_ray_count]. </constant> <constant name="BAKE_QUALITY_HIGH" value="2" enum="BakeQuality"> + High bake quality (slow bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/high_quality_probe_ray_count]. </constant> <constant name="BAKE_QUALITY_ULTRA" value="3" enum="BakeQuality"> + Highest bake quality (slowest bake times). The quality of this preset can be adjusted by changing [member ProjectSettings.rendering/lightmapping/bake_quality/high_quality_ray_count] and [member ProjectSettings.rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count]. </constant> <constant name="GENERATE_PROBES_DISABLED" value="0" enum="GenerateProbes"> + Don't generate lightmap probes for lighting dynamic objects. </constant> <constant name="GENERATE_PROBES_SUBDIV_4" value="1" enum="GenerateProbes"> + Lowest level of subdivision (fastest bake times, smallest file sizes). </constant> <constant name="GENERATE_PROBES_SUBDIV_8" value="2" enum="GenerateProbes"> + Low level of subdivision (fast bake times, small file sizes). </constant> <constant name="GENERATE_PROBES_SUBDIV_16" value="3" enum="GenerateProbes"> + High level of subdivision (slow bake times, large file sizes). </constant> <constant name="GENERATE_PROBES_SUBDIV_32" value="4" enum="GenerateProbes"> + Highest level of subdivision (slowest bake times, largest file sizes). </constant> <constant name="BAKE_ERROR_OK" value="0" enum="BakeError"> + Lightmap baking was successful. </constant> <constant name="BAKE_ERROR_NO_LIGHTMAPPER" value="1" enum="BakeError"> + Lightmap baking failed as there is no lightmapper available in this Godot build. </constant> <constant name="BAKE_ERROR_NO_SAVE_PATH" value="2" enum="BakeError"> + Lightmap baking failed as the [LightmapGIData] save path isn't configured in the resource. </constant> <constant name="BAKE_ERROR_NO_MESHES" value="3" enum="BakeError"> + Lightmap baking failed as there are no meshes whose [member GeometryInstance3D.gi_mode] is [constant GeometryInstance3D.GI_MODE_STATIC] and with valid UV2 mapping in the current scene. You may need to select 3D scenes in the Import dock and change their global illumination mode accordingly. </constant> <constant name="BAKE_ERROR_MESHES_INVALID" value="4" enum="BakeError"> + Lightmap baking failed as the lightmapper failed to analyze some of the meshes marked as static for baking. </constant> <constant name="BAKE_ERROR_CANT_CREATE_IMAGE" value="5" enum="BakeError"> + Lightmap baking failed as the resulting image couldn't be saved or imported by Godot after it was saved. </constant> <constant name="BAKE_ERROR_USER_ABORTED" value="6" enum="BakeError"> + The user aborted the lightmap baking operation (typically by clicking the [b]Cancel[/b] button in the progress dialog). </constant> <constant name="ENVIRONMENT_MODE_DISABLED" value="0" enum="EnvironmentMode"> + Ignore environment lighting when baking lightmaps. </constant> <constant name="ENVIRONMENT_MODE_SCENE" value="1" enum="EnvironmentMode"> + Use the scene's environment lighting when baking lightmaps. + [b]Note:[/b] If baking lightmaps in a scene with no [WorldEnvironment] node, this will act like [constant ENVIRONMENT_MODE_DISABLED]. The editor's preview sky and sun is [i]not[/i] taken into account by [LightmapGI] when baking lightmaps. </constant> <constant name="ENVIRONMENT_MODE_CUSTOM_SKY" value="2" enum="EnvironmentMode"> + Use [member environment_custom_sky] as a source of environment lighting when baking lightmaps. </constant> <constant name="ENVIRONMENT_MODE_CUSTOM_COLOR" value="3" enum="EnvironmentMode"> + Use [member environment_custom_color] multiplied by [member environment_custom_energy] as a constant source of environment lighting when baking lightmaps. </constant> </constants> </class> diff --git a/doc/classes/LightmapGIData.xml b/doc/classes/LightmapGIData.xml index c2423daef0..20113ac309 100644 --- a/doc/classes/LightmapGIData.xml +++ b/doc/classes/LightmapGIData.xml @@ -1,8 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="LightmapGIData" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Contains baked lightmap and dynamic object probe data for [LightmapGI]. </brief_description> <description> + [LightmapGIData] contains baked lightmap and dynamic object probe data for [LightmapGI]. It is replaced every time lightmaps are baked in [LightmapGI]. </description> <tutorials> </tutorials> @@ -14,38 +16,46 @@ <argument index="2" name="slice_index" type="int" /> <argument index="3" name="sub_instance" type="int" /> <description> + Adds an object that is considered baked within this [LightmapGIData]. </description> </method> <method name="clear_users"> <return type="void" /> <description> + Clear all objects that are considred baked within this [LightmapGIData]. </description> </method> <method name="get_user_count" qualifiers="const"> <return type="int" /> <description> + Returns the number of objects that are considered baked within this [LightmapGIData]. </description> </method> <method name="get_user_path" qualifiers="const"> <return type="NodePath" /> <argument index="0" name="user_idx" type="int" /> <description> + Returns the [NodePath] of the baked object at index [code]user_idx[/code]. </description> </method> <method name="is_using_spherical_harmonics" qualifiers="const"> <return type="bool" /> <description> + If [code]true[/code], lightmaps were baked with directional information. See also [member LightmapGI.directional]. </description> </method> <method name="set_uses_spherical_harmonics"> <return type="void" /> <argument index="0" name="uses_spherical_harmonics" type="bool" /> <description> + If [code]uses_spherical_harmonics[/code] is [code]true[/code], tells the engine to treat the lightmap data as if it was baked with directional information. + [b]Note:[/b] Changing this value on already baked lightmaps will not cause them to be baked again. This means the material appearance will look incorrect until lightmaps are baked again, in which case the value set here is discarded as the entire [LightmapGIData] resource is replaced by the lightmapper. </description> </method> </methods> <members> <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture"> + The lightmap atlas texture generated by the lightmapper. </member> </members> </class> diff --git a/doc/classes/LightmapProbe.xml b/doc/classes/LightmapProbe.xml index a5ba6294b9..cb4879b6c7 100644 --- a/doc/classes/LightmapProbe.xml +++ b/doc/classes/LightmapProbe.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="LightmapProbe" inherits="Node3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Represents a single manually placed probe for dynamic object lighting with [LightmapGI]. </brief_description> <description> + [LightmapProbe] represents the position of a single manually placed probe for dynamic object lighting with [LightmapGI]. + Typically, [LightmapGI] probes are placed automatically by setting [member LightmapGI.generate_probes_subdiv] to a value other than [constant LightmapGI.GENERATE_PROBES_DISABLED]. By creating [LightmapProbe] nodes before baking lightmaps, you can add more probes in specific areas for greater detail, or disable automatic generation and rely only on manually placed probes instead. </description> <tutorials> </tutorials> diff --git a/doc/classes/Lightmapper.xml b/doc/classes/Lightmapper.xml index f9a1e2fa99..58ef2ed0cf 100644 --- a/doc/classes/Lightmapper.xml +++ b/doc/classes/Lightmapper.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Lightmapper" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Abstract class extended by lightmappers, for use in [LightmapGI]. </brief_description> <description> + This class should be extended by custom lightmapper classes. Lightmappers can then be used with [LightmapGI] to provide fast baked global illumination in 3D. + Godot contains a built-in GPU-based lightmapper [LightmapperRD] that uses compute shaders, but custom lightmappers can be implemented by C++ modules. </description> <tutorials> </tutorials> diff --git a/doc/classes/LightmapperRD.xml b/doc/classes/LightmapperRD.xml index 29d95244ce..e4b68a7ef8 100644 --- a/doc/classes/LightmapperRD.xml +++ b/doc/classes/LightmapperRD.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="LightmapperRD" inherits="Lightmapper" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + The built-in GPU-based lightmapper for use with [LightmapGI]. </brief_description> <description> + LightmapperRD ("RD" stands for [RenderingDevice]) is the built-in GPU-based lightmapper for use with [LightmapGI]. On most dedicated GPUs, it can bake lightmaps much faster than most CPU-based lightmappers. LightmapperRD uses compute shaders to bake lightmaps, so it does not require CUDA or OpenCL libraries to be installed to be usable. + [b]Note:[/b] Only usable when using the Vulkan backend (Clustered or Mobile), not OpenGL. </description> <tutorials> </tutorials> diff --git a/doc/classes/MeshInstance2D.xml b/doc/classes/MeshInstance2D.xml index 96e66f850a..e9666337a1 100644 --- a/doc/classes/MeshInstance2D.xml +++ b/doc/classes/MeshInstance2D.xml @@ -4,7 +4,7 @@ Node used for displaying a [Mesh] in 2D. </brief_description> <description> - Node used for displaying a [Mesh] in 2D. Can be constructed from an existing [Sprite2D] via a tool in the editor toolbar. Select "Sprite2D" then "Convert to Mesh2D", select settings in popup and press "Create Mesh2D". + Node used for displaying a [Mesh] in 2D. A [MeshInstance2D] can be automatically created from an existing [Sprite2D] via a tool in the editor toolbar. Select the [Sprite2D] node, then choose [b]Sprite2D > Convert to MeshInstance2D[/b] at the top of the 2D editor viewport. </description> <tutorials> <link title="2D meshes">$DOCS_URL/tutorials/2d/2d_meshes.html</link> diff --git a/doc/classes/NavigationAgent2D.xml b/doc/classes/NavigationAgent2D.xml index 945947ad9f..0ac9513464 100644 --- a/doc/classes/NavigationAgent2D.xml +++ b/doc/classes/NavigationAgent2D.xml @@ -34,6 +34,12 @@ Returns which index the agent is currently on in the navigation path's [PackedVector2Array]. </description> </method> + <method name="get_navigation_map" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of the navigation map for this NavigationAgent node. This function returns always the map set on the NavigationAgent node and not the map of the abstract agent on the NavigationServer. If the agent map is changed directly with the NavigationServer API the NavigationAgent node will not be aware of the map change. Use [method set_navigation_map] to change the navigation map for the NavigationAgent and also update the agent on the NavigationServer. + </description> + </method> <method name="get_next_location"> <return type="Vector2" /> <description> @@ -70,6 +76,13 @@ Returns true if the target location is reached. The target location is set using [method set_target_location]. It may not always be possible to reach the target location. It should always be possible to reach the final location though. See [method get_final_location]. </description> </method> + <method name="set_navigation_map"> + <return type="void" /> + <argument index="0" name="navigation_map" type="RID" /> + <description> + Sets the [RID] of the navigation map this NavigationAgent node should use and also updates the [code]agent[/code] on the NavigationServer. + </description> + </method> <method name="set_target_location"> <return type="void" /> <argument index="0" name="location" type="Vector2" /> @@ -95,8 +108,8 @@ <member name="max_speed" type="float" setter="set_max_speed" getter="get_max_speed" default="200.0"> The maximum speed that an agent can move. </member> - <member name="navigable_layers" type="int" setter="set_navigable_layers" getter="get_navigable_layers" default="1"> - A bitfield determining what layers of navigation regions this agent will use to calculate path. Changing it runtime will clear current navigation path and generate new one, according to new layers. + <member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1"> + A bitfield determining what navigation layers of navigation regions this agent will use to calculate path. Changing it runtime will clear current navigation path and generate new one, according to new navigation layers. </member> <member name="neighbor_dist" type="float" setter="set_neighbor_dist" getter="get_neighbor_dist" default="500.0"> The distance to search for other agents. diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml index 7f7e058742..cc45a43ffc 100644 --- a/doc/classes/NavigationAgent3D.xml +++ b/doc/classes/NavigationAgent3D.xml @@ -34,6 +34,12 @@ Returns which index the agent is currently on in the navigation path's [PackedVector3Array]. </description> </method> + <method name="get_navigation_map" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of the navigation map for this NavigationAgent node. This function returns always the map set on the NavigationAgent node and not the map of the abstract agent on the NavigationServer. If the agent map is changed directly with the NavigationServer API the NavigationAgent node will not be aware of the map change. Use [method set_navigation_map] to change the navigation map for the NavigationAgent and also update the agent on the NavigationServer. + </description> + </method> <method name="get_next_location"> <return type="Vector3" /> <description> @@ -70,6 +76,13 @@ Returns true if the target location is reached. The target location is set using [method set_target_location]. It may not always be possible to reach the target location. It should always be possible to reach the final location though. See [method get_final_location]. </description> </method> + <method name="set_navigation_map"> + <return type="void" /> + <argument index="0" name="navigation_map" type="RID" /> + <description> + Sets the [RID] of the navigation map this NavigationAgent node should use and also updates the [code]agent[/code] on the NavigationServer. + </description> + </method> <method name="set_target_location"> <return type="void" /> <argument index="0" name="location" type="Vector3" /> @@ -101,8 +114,8 @@ <member name="max_speed" type="float" setter="set_max_speed" getter="get_max_speed" default="10.0"> The maximum speed that an agent can move. </member> - <member name="navigable_layers" type="int" setter="set_navigable_layers" getter="get_navigable_layers" default="1"> - A bitfield determining what layers of navigation regions this agent will use to calculate path. Changing it runtime will clear current navigation path and generate new one, according to new layers. + <member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1"> + A bitfield determining what navigation layers of navigation regions this NavigationAgent will use to calculate path. Changing it runtime will clear current navigation path and generate new one, according to new navigation layers. </member> <member name="neighbor_dist" type="float" setter="set_neighbor_dist" getter="get_neighbor_dist" default="50.0"> The distance to search for other agents. diff --git a/doc/classes/NavigationRegion2D.xml b/doc/classes/NavigationRegion2D.xml index 542aa8f619..62e64f2a3c 100644 --- a/doc/classes/NavigationRegion2D.xml +++ b/doc/classes/NavigationRegion2D.xml @@ -28,8 +28,8 @@ <member name="enter_cost" type="float" setter="set_enter_cost" getter="get_enter_cost" default="0.0"> When pathfinding enters this regions navmesh from another regions navmesh the [code]enter_cost[/code] value is added to the path distance for determining the shortest path. </member> - <member name="layers" type="int" setter="set_layers" getter="get_layers" default="1"> - A bitfield determining all layers the region belongs to. These layers can be checked upon when requesting a path with [method NavigationServer2D.map_get_path]. + <member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1"> + A bitfield determining all navigation layers the region belongs to. These navigation layers can be checked upon when requesting a path with [method NavigationServer2D.map_get_path]. </member> <member name="navpoly" type="NavigationPolygon" setter="set_navigation_polygon" getter="get_navigation_polygon"> The [NavigationPolygon] resource to use. diff --git a/doc/classes/NavigationRegion3D.xml b/doc/classes/NavigationRegion3D.xml index e45bca7f8b..3af7fe5c97 100644 --- a/doc/classes/NavigationRegion3D.xml +++ b/doc/classes/NavigationRegion3D.xml @@ -35,8 +35,8 @@ <member name="enter_cost" type="float" setter="set_enter_cost" getter="get_enter_cost" default="0.0"> When pathfinding enters this regions navmesh from another regions navmesh the [code]enter_cost[/code] value is added to the path distance for determining the shortest path. </member> - <member name="layers" type="int" setter="set_layers" getter="get_layers" default="1"> - A bitfield determining all layers the region belongs to. These layers can be checked upon when requesting a path with [method NavigationServer3D.map_get_path]. + <member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1"> + A bitfield determining all navigation layers the region belongs to. These navigation layers can be checked upon when requesting a path with [method NavigationServer3D.map_get_path]. </member> <member name="navmesh" type="NavigationMesh" setter="set_navigation_mesh" getter="get_navigation_mesh"> The [NavigationMesh] resource to use. diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index 7b0dac99c3..220c12ce7f 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -8,7 +8,7 @@ Maps are made up of regions, which are made of navigation polygons. Together, they define the navigable areas in the 2D world. [b]Note:[/b] Most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation related Nodes in the SceneTree or made through scripts. For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than [code]edge_connection_margin[/code] to the respective other edge's vertex. - You may assign navigation layers to regions with [method NavigationServer2D.region_set_layers], which then can be checked upon when requesting a path with [method NavigationServer2D.map_get_path]. This allows allowing or forbidding some areas to 2D objects. + You may assign navigation layers to regions with [method NavigationServer2D.region_set_navigation_layers], which then can be checked upon when requesting a path with [method NavigationServer2D.map_get_path]. This allows allowing or forbidding some areas to 2D objects. To use the collision avoidance system, you may use agents. You can set an agent's target velocity, then the servers will emit a callback with a modified velocity. [b]Note:[/b] 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. 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. @@ -44,7 +44,8 @@ <argument index="2" name="method" type="StringName" /> <argument index="3" name="userdata" type="Variant" default="null" /> <description> - Callback called at the end of the RVO process. + Callback called at the end of the RVO process. If a callback is created manually and the agent is placed on a navigation map it will calculate avoidance for the agent and dispatch the calculated [code]safe_velocity[/code] to the [code]receiver[/code] object with a signal to the chosen [code]method[/code] name. + [b]Note:[/b] Created callbacks are always processed independently of the SceneTree state as long as the agent is on a navigation map and not freed. To disable the dispatch of a callback from an agent use [method agent_set_callback] again with a [code]null[/code] object as the [code]receiver[/code]. </description> </method> <method name="agent_set_map" qualifiers="const"> @@ -175,9 +176,9 @@ <argument index="1" name="origin" type="Vector2" /> <argument index="2" name="destination" type="Vector2" /> <argument index="3" name="optimize" type="bool" /> - <argument index="4" name="layers" type="int" default="1" /> + <argument index="4" name="navigation_layers" type="int" default="1" /> <description> - Returns the navigation path to reach the destination from the origin. [code]layers[/code] is a bitmask of all region layers that are allowed to be in the path. + Returns the navigation path to reach the destination from the origin. [code]navigation_layers[/code] is a bitmask of all region navigation layers that are allowed to be in the path. </description> </method> <method name="map_get_regions" qualifiers="const"> @@ -254,18 +255,18 @@ Returns the [code]enter_cost[/code] of this [code]region[/code]. </description> </method> - <method name="region_get_layers" qualifiers="const"> - <return type="int" /> + <method name="region_get_map" qualifiers="const"> + <return type="RID" /> <argument index="0" name="region" type="RID" /> <description> - Returns the region's layers. + Returns the navigation map [RID] the requested [code]region[/code] is currently assigned to. </description> </method> - <method name="region_get_map" qualifiers="const"> - <return type="RID" /> + <method name="region_get_navigation_layers" qualifiers="const"> + <return type="int" /> <argument index="0" name="region" type="RID" /> <description> - Returns the navigation map [RID] the requested [code]region[/code] is currently assigned to. + Returns the region's navigation layers. </description> </method> <method name="region_get_travel_cost" qualifiers="const"> @@ -283,20 +284,20 @@ Sets the [code]enter_cost[/code] for this [code]region[/code]. </description> </method> - <method name="region_set_layers" qualifiers="const"> + <method name="region_set_map" qualifiers="const"> <return type="void" /> <argument index="0" name="region" type="RID" /> - <argument index="1" name="layers" type="int" /> + <argument index="1" name="map" type="RID" /> <description> - Set the region's layers. This allows selecting regions from a path request (when using [method NavigationServer2D.map_get_path]). + Sets the map for the region. </description> </method> - <method name="region_set_map" qualifiers="const"> + <method name="region_set_navigation_layers" qualifiers="const"> <return type="void" /> <argument index="0" name="region" type="RID" /> - <argument index="1" name="map" type="RID" /> + <argument index="1" name="navigation_layers" type="int" /> <description> - Sets the map for the region. + Set the region's navigation layers. This allows selecting regions from a path request (when using [method NavigationServer2D.map_get_path]). </description> </method> <method name="region_set_navpoly" qualifiers="const"> diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index d6574dd69a..d2eef49cfd 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -8,7 +8,7 @@ Maps are made up of regions, which are made of navigation meshes. Together, they define the navigable areas in the 3D world. [b]Note:[/b] Most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation related Nodes in the SceneTree or made through scripts. For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than [code]edge_connection_margin[/code] to the respective other edge's vertex. - You may assign navigation layers to regions with [method NavigationServer3D.region_set_layers], which then can be checked upon when requesting a path with [method NavigationServer3D.map_get_path]. This allows allowing or forbidding some areas to 3D objects. + You may assign navigation layers to regions with [method NavigationServer3D.region_set_navigation_layers], which then can be checked upon when requesting a path with [method NavigationServer3D.map_get_path]. This allows allowing or forbidding some areas to 3D objects. To use the collision avoidance system, you may use agents. You can set an agent's target velocity, then the servers will emit a callback with a modified velocity. [b]Note:[/b] 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. 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. @@ -44,7 +44,8 @@ <argument index="2" name="method" type="StringName" /> <argument index="3" name="userdata" type="Variant" default="null" /> <description> - Callback called at the end of the RVO process. + Callback called at the end of the RVO process. If a callback is created manually and the agent is placed on a navigation map it will calculate avoidance for the agent and dispatch the calculated [code]safe_velocity[/code] to the [code]receiver[/code] object with a signal to the chosen [code]method[/code] name. + [b]Note:[/b] Created callbacks are always processed independently of the SceneTree state as long as the agent is on a navigation map and not freed. To disable the dispatch of a callback from an agent use [method agent_set_callback] again with a [code]null[/code] object as the [code]receiver[/code]. </description> </method> <method name="agent_set_map" qualifiers="const"> @@ -193,9 +194,9 @@ <argument index="1" name="origin" type="Vector3" /> <argument index="2" name="destination" type="Vector3" /> <argument index="3" name="optimize" type="bool" /> - <argument index="4" name="layers" type="int" default="1" /> + <argument index="4" name="navigation_layers" type="int" default="1" /> <description> - Returns the navigation path to reach the destination from the origin. [code]layers[/code] is a bitmask of all region layers that are allowed to be in the path. + Returns the navigation path to reach the destination from the origin. [code]navigation_layers[/code] is a bitmask of all region navigation layers that are allowed to be in the path. </description> </method> <method name="map_get_regions" qualifiers="const"> @@ -304,18 +305,18 @@ Returns the [code]enter_cost[/code] of this [code]region[/code]. </description> </method> - <method name="region_get_layers" qualifiers="const"> - <return type="int" /> + <method name="region_get_map" qualifiers="const"> + <return type="RID" /> <argument index="0" name="region" type="RID" /> <description> - Returns the region's layers. + Returns the navigation map [RID] the requested [code]region[/code] is currently assigned to. </description> </method> - <method name="region_get_map" qualifiers="const"> - <return type="RID" /> + <method name="region_get_navigation_layers" qualifiers="const"> + <return type="int" /> <argument index="0" name="region" type="RID" /> <description> - Returns the navigation map [RID] the requested [code]region[/code] is currently assigned to. + Returns the region's navigation layers. </description> </method> <method name="region_get_travel_cost" qualifiers="const"> @@ -333,20 +334,20 @@ Sets the [code]enter_cost[/code] for this [code]region[/code]. </description> </method> - <method name="region_set_layers" qualifiers="const"> + <method name="region_set_map" qualifiers="const"> <return type="void" /> <argument index="0" name="region" type="RID" /> - <argument index="1" name="layers" type="int" /> + <argument index="1" name="map" type="RID" /> <description> - Set the region's layers. This allows selecting regions from a path request (when using [method NavigationServer3D.map_get_path]). + Sets the map for the region. </description> </method> - <method name="region_set_map" qualifiers="const"> + <method name="region_set_navigation_layers" qualifiers="const"> <return type="void" /> <argument index="0" name="region" type="RID" /> - <argument index="1" name="map" type="RID" /> + <argument index="1" name="navigation_layers" type="int" /> <description> - Sets the map for the region. + Set the region's navigation layers. This allows selecting regions from a path request (when using [method NavigationServer3D.map_get_path]). </description> </method> <method name="region_set_navmesh" qualifiers="const"> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 2512dec4b3..e6d5ea61da 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -469,7 +469,12 @@ <argument index="0" name="path" type="String" /> <description> Moves the file or directory to the system's recycle bin. See also [method Directory.remove]. + The method takes only global paths, so you may need to use [method ProjectSettings.globalize_path]. Do not use it for files in [code]res://[/code] as it will not work in exported project. [b]Note:[/b] If the user has disabled the recycle bin on their system, the file will be permanently deleted instead. + [codeblock] + var file_to_remove = "user://slot1.sav" + OS.move_to_trash(ProjectSettings.globalize_path(file_to_remove)) + [/codeblock] </description> </method> <method name="open_midi_inputs"> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 42844794b0..11ae7cc2b0 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -325,7 +325,7 @@ </method> <method name="get" qualifiers="const"> <return type="Variant" /> - <argument index="0" name="property" type="String" /> + <argument index="0" name="property" type="StringName" /> <description> Returns the [Variant] value of the given [code]property[/code]. If the [code]property[/code] doesn't exist, this will return [code]null[/code]. [b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase). @@ -399,7 +399,7 @@ </method> <method name="get_signal_connection_list" qualifiers="const"> <return type="Array" /> - <argument index="0" name="signal" type="String" /> + <argument index="0" name="signal" type="StringName" /> <description> Returns an [Array] of connections for the given [code]signal[/code]. </description> @@ -490,7 +490,7 @@ </method> <method name="set"> <return type="void" /> - <argument index="0" name="property" type="String" /> + <argument index="0" name="property" type="StringName" /> <argument index="1" name="value" type="Variant" /> <description> Assigns a new value to the given property. If the [code]property[/code] does not exist or the given value's type doesn't match, nothing will happen. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 8a3677c0b4..25f0a997ba 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -1714,28 +1714,40 @@ <member name="rendering/global_illumination/voxel_gi/quality" type="int" setter="" getter="" default="0"> </member> <member name="rendering/lightmapping/bake_performance/max_rays_per_pass" type="int" setter="" getter="" default="32"> + The maximum number of rays that can be thrown per pass when baking lightmaps with [LightmapGI]. Depending on the scene, adjusting this value may result in higher GPU utilization when baking lightmaps, leading to faster bake times. </member> <member name="rendering/lightmapping/bake_performance/max_rays_per_probe_pass" type="int" setter="" getter="" default="64"> + The maximum number of rays that can be thrown per pass when baking dynamic object lighting in [LightmapProbe]s with [LightmapGI]. Depending on the scene, adjusting this value may result in higher GPU utilization when baking lightmaps, leading to faster bake times. </member> <member name="rendering/lightmapping/bake_performance/region_size" type="int" setter="" getter="" default="512"> + The region size to use when baking lightmaps with [LightmapGI]. </member> <member name="rendering/lightmapping/bake_quality/high_quality_probe_ray_count" type="int" setter="" getter="" default="512"> + The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_HIGH]. </member> <member name="rendering/lightmapping/bake_quality/high_quality_ray_count" type="int" setter="" getter="" default="256"> + The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_HIGH]. </member> <member name="rendering/lightmapping/bake_quality/low_quality_probe_ray_count" type="int" setter="" getter="" default="64"> + The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_LOW]. </member> <member name="rendering/lightmapping/bake_quality/low_quality_ray_count" type="int" setter="" getter="" default="16"> + The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_LOW]. </member> <member name="rendering/lightmapping/bake_quality/medium_quality_probe_ray_count" type="int" setter="" getter="" default="256"> + The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_MEDIUM]. </member> <member name="rendering/lightmapping/bake_quality/medium_quality_ray_count" type="int" setter="" getter="" default="64"> + The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_MEDIUM]. </member> <member name="rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count" type="int" setter="" getter="" default="2048"> + The number of rays to use for baking dynamic object lighting in [LightmapProbe]s when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_ULTRA]. </member> <member name="rendering/lightmapping/bake_quality/ultra_quality_ray_count" type="int" setter="" getter="" default="1024"> + The number of rays to use for baking lightmaps with [LightmapGI] when [member LightmapGI.quality] is [constant LightmapGI.BAKE_QUALITY_ULTRA]. </member> <member name="rendering/lightmapping/probe_capture/update_speed" type="float" setter="" getter="" default="15"> + The framerate-independent update speed when representing dynamic object lighting from [LightmapProbe]s. Higher values make dynamic object lighting update faster. Higher values can prevent fast-moving objects from having "outdated" indirect lighting displayed on them, at the cost of possible flickering when an object moves from a bright area to a shaded area. </member> <member name="rendering/limits/cluster_builder/max_clustered_elements" type="float" setter="" getter="" default="512"> </member> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 1f3d5596aa..f4d453700c 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -412,9 +412,9 @@ </method> <method name="left" qualifiers="const"> <return type="String" /> - <argument index="0" name="position" type="int" /> + <argument index="0" name="length" type="int" /> <description> - Returns a number of characters from the left of the string. If negative [code]position[/code] is used, the characters are counted downwards from [String]'s length. + Returns a number of characters from the left of the string. If negative [code]length[/code] is used, the characters are counted downwards from [String]'s length. Examples: [codeblock] print("sample text".left(3)) #prints "sam" @@ -599,9 +599,9 @@ </method> <method name="right" qualifiers="const"> <return type="String" /> - <argument index="0" name="position" type="int" /> + <argument index="0" name="length" type="int" /> <description> - Returns a number of characters from the right of the string. If negative [code]position[/code] is used, the characters are counted downwards from [String]'s length. + Returns a number of characters from the right of the string. If negative [code]length[/code] is used, the characters are counted downwards from [String]'s length. Examples: [codeblock] print("sample text".right(3)) #prints "ext" diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index 2f57b76374..19be38b323 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -121,6 +121,20 @@ Returns font embolden strength. </description> </method> + <method name="font_get_face_count" qualifiers="const"> + <return type="int" /> + <argument index="0" name="font_rid" type="RID" /> + <description> + Returns number of faces in the TrueType / OpenType collection. + </description> + </method> + <method name="font_get_face_index" qualifiers="const"> + <return type="int" /> + <argument index="0" name="font_rid" type="RID" /> + <description> + Recturns an active face index in the TrueType / OpenType collection. + </description> + </method> <method name="font_get_fixed_size" qualifiers="const"> <return type="int" /> <argument index="0" name="font_rid" type="RID" /> @@ -593,6 +607,14 @@ Sets font embolden strength. If [code]strength[/code] is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness. </description> </method> + <method name="font_set_face_index"> + <return type="void" /> + <argument index="0" name="font_rid" type="RID" /> + <argument index="1" name="face_index" type="int" /> + <description> + Sets an active face index in the TrueType / OpenType collection. + </description> + </method> <method name="font_set_fixed_size"> <return type="void" /> <argument index="0" name="font_rid" type="RID" /> diff --git a/doc/classes/TextServerExtension.xml b/doc/classes/TextServerExtension.xml index 434d6f909c..b3be858ca1 100644 --- a/doc/classes/TextServerExtension.xml +++ b/doc/classes/TextServerExtension.xml @@ -114,6 +114,20 @@ Returns font embolden strength. </description> </method> + <method name="font_get_face_count" qualifiers="virtual const"> + <return type="int" /> + <argument index="0" name="font_rid" type="RID" /> + <description> + Returns number of faces in the TrueType / OpenType collection. + </description> + </method> + <method name="font_get_face_index" qualifiers="virtual const"> + <return type="int" /> + <argument index="0" name="font_rid" type="RID" /> + <description> + Returns an active face index in the TrueType / OpenType collection. + </description> + </method> <method name="font_get_fixed_size" qualifiers="virtual const"> <return type="int" /> <argument index="0" name="font_rid" type="RID" /> @@ -590,6 +604,14 @@ Sets font embolden strength. If [code]strength[/code] is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness. </description> </method> + <method name="font_set_face_index" qualifiers="virtual"> + <return type="void" /> + <argument index="0" name="font_rid" type="RID" /> + <argument index="1" name="face_index" type="int" /> + <description> + Sets an active face index in the TrueType / OpenType collection. + </description> + </method> <method name="font_set_fixed_size" qualifiers="virtual"> <return type="void" /> <argument index="0" name="font_rid" type="RID" /> diff --git a/doc/classes/TileData.xml b/doc/classes/TileData.xml index d5c2693f8b..0c2961fd5e 100644 --- a/doc/classes/TileData.xml +++ b/doc/classes/TileData.xml @@ -79,7 +79,7 @@ Returns the occluder polygon of the tile for the TileSet occlusion layer with index [code]layer_id[/code]. </description> </method> - <method name="get_peering_bit_terrain" qualifiers="const"> + <method name="get_terrain_peering_bit" qualifiers="const"> <return type="int" /> <argument index="0" name="peering_bit" type="int" enum="TileSet.CellNeighbor" /> <description> @@ -185,7 +185,7 @@ Sets the occluder for the TileSet occlusion layer with index [code]layer_id[/code]. </description> </method> - <method name="set_peering_bit_terrain"> + <method name="set_terrain_peering_bit"> <return type="void" /> <argument index="0" name="peering_bit" type="int" enum="TileSet.CellNeighbor" /> <argument index="1" name="terrain" type="int" /> @@ -205,6 +205,8 @@ </member> <member name="probability" type="float" setter="set_probability" getter="get_probability" default="1.0"> </member> + <member name="terrain" type="int" setter="set_terrain" getter="get_terrain" default="-1"> + </member> <member name="terrain_set" type="int" setter="set_terrain_set" getter="get_terrain_set" default="-1"> </member> <member name="texture_offset" type="Vector2i" setter="set_texture_offset" getter="get_texture_offset" default="Vector2i(0, 0)"> diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index 259c800a78..d532f583e6 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -243,15 +243,30 @@ - The alternative tile identifier [code]alternative_tile[/code] identifies a tile alternative the source is a [TileSetAtlasSource], and the scene for a [TileSetScenesCollectionSource]. </description> </method> - <method name="set_cells_from_surrounding_terrains"> + <method name="set_cells_terrain_connect"> <return type="void" /> <argument index="0" name="layer" type="int" /> <argument index="1" name="cells" type="Vector2i[]" /> <argument index="2" name="terrain_set" type="int" /> - <argument index="3" name="ignore_empty_terrains" type="bool" default="true" /> + <argument index="3" name="terrain" type="int" /> + <argument index="4" name="ignore_empty_terrains" type="bool" default="true" /> <description> - Updates all the cells in the [code]cells[/code] coordinates array and replace them by tiles that matches the surrounding cells terrains. Only cells form the given [code]terrain_set[/code] are considered. - If [code]ignore_empty_terrains[/code] is true, zones with no terrain defined are ignored to select the tiles. + Update all the cells in the [code]cells[/code] coordinates array so that they use the given [code]terrain[/code] for the given [code]terrain_set[/code]. If an updated cell has the same terrain as one of its neighboring cells, this function tries to join the two. This function might update neighboring tiles if needed to create correct terrain transitions. If [code]ignore_empty_terrains[/code] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + If [code]ignore_empty_terrains[/code] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + [b]Note:[/b] To work correctly, [code]set_cells_terrain_connect[/code] requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. + </description> + </method> + <method name="set_cells_terrain_path"> + <return type="void" /> + <argument index="0" name="layer" type="int" /> + <argument index="1" name="path" type="Vector2i[]" /> + <argument index="2" name="terrain_set" type="int" /> + <argument index="3" name="terrain" type="int" /> + <argument index="4" name="ignore_empty_terrains" type="bool" default="true" /> + <description> + Update all the cells in the [code]cells[/code] coordinates array so that they use the given [code]terrain[/code] for the given [code]terrain_set[/code]. The function will also connect two successive cell in the path with the same terrain. This function might update neighboring tiles if needed to create correct terrain transitions. + If [code]ignore_empty_terrains[/code] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + [b]Note:[/b] To work correctly, [code]set_cells_terrain_path[/code] requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. </description> </method> <method name="set_layer_enabled"> diff --git a/doc/classes/WorldEnvironment.xml b/doc/classes/WorldEnvironment.xml index 8afe169874..ed8f0b9a04 100644 --- a/doc/classes/WorldEnvironment.xml +++ b/doc/classes/WorldEnvironment.xml @@ -16,6 +16,7 @@ </tutorials> <members> <member name="camera_effects" type="CameraEffects" setter="set_camera_effects" getter="get_camera_effects"> + The [CameraEffects] resource used by this [WorldEnvironment], defining the default properties. This [CameraEffects] resource will be used by all [Camera3D]s that do not define their own [CameraEffects]. </member> <member name="environment" type="Environment" setter="set_environment" getter="get_environment"> The [Environment] resource used by this [WorldEnvironment], defining the default properties. diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 2e227ce578..f59f2ff872 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -4,7 +4,9 @@ import argparse import os +import platform import re +import sys import xml.etree.ElementTree as ET from collections import OrderedDict @@ -55,9 +57,11 @@ BASE_STRINGS = [ ] strings_l10n = {} +STYLES = {} + def print_error(error, state): # type: (str, State) -> None - print("ERROR: {}".format(error)) + print("{}{}ERROR:{} {}{}".format(STYLES["red"], STYLES["bold"], STYLES["regular"], error, STYLES["reset"])) state.num_errors += 1 @@ -399,10 +403,26 @@ def parse_arguments(root): # type: (ET.Element) -> List[ParameterDef] def main(): # type: () -> None + # Enable ANSI escape code support on Windows 10 and later (for colored console output). + # <https://bugs.python.org/issue29059> + if platform.system().lower() == "windows": + from ctypes import windll, c_int, byref + + stdout_handle = windll.kernel32.GetStdHandle(c_int(-11)) + mode = c_int(0) + windll.kernel32.GetConsoleMode(c_int(stdout_handle), byref(mode)) + mode = c_int(mode.value | 4) + windll.kernel32.SetConsoleMode(c_int(stdout_handle), mode) + parser = argparse.ArgumentParser() parser.add_argument("path", nargs="+", help="A path to an XML file or a directory containing XML files to parse.") parser.add_argument("--filter", default="", help="The filepath pattern for XML files to filter.") parser.add_argument("--lang", "-l", default="en", help="Language to use for section headings.") + parser.add_argument( + "--color", + action="store_true", + help="If passed, force colored output even if stdout is not a TTY (useful for continuous integration).", + ) group = parser.add_mutually_exclusive_group() group.add_argument("--output", "-o", default=".", help="The directory to save output .rst files in.") group.add_argument( @@ -412,6 +432,13 @@ def main(): # type: () -> None ) args = parser.parse_args() + should_color = args.color or (hasattr(sys.stdout, "isatty") and sys.stdout.isatty()) + STYLES["red"] = "\x1b[91m" if should_color else "" + STYLES["green"] = "\x1b[92m" if should_color else "" + STYLES["bold"] = "\x1b[1m" if should_color else "" + STYLES["regular"] = "\x1b[22m" if should_color else "" + STYLES["reset"] = "\x1b[0m" if should_color else "" + # Retrieve heading translations for the given language. if not args.dry_run and args.lang != "en": lang_file = os.path.join( @@ -464,17 +491,17 @@ def main(): # type: () -> None try: tree = ET.parse(cur_file) except ET.ParseError as e: - print_error("{}.xml: Parse error while reading the file: {}".format(cur_file, e), state) + print_error("{}: Parse error while reading the file: {}".format(cur_file, e), state) continue doc = tree.getroot() if "version" not in doc.attrib: - print_error('{}.xml: "version" attribute missing from "doc".'.format(cur_file), state) + print_error('{}: "version" attribute missing from "doc".'.format(cur_file), state) continue name = doc.attrib["name"] if name in classes: - print_error('{}.xml: Duplicate class "{}".'.format(cur_file, name), state) + print_error('{}: Duplicate class "{}".'.format(cur_file, name), state) continue classes[name] = (doc, cur_file) @@ -499,16 +526,22 @@ def main(): # type: () -> None make_rst_class(class_def, state, args.dry_run, args.output) if state.num_errors == 0: - print("No errors found in the class reference XML.") + print("{}No errors found in the class reference XML.{}".format(STYLES["green"], STYLES["reset"])) if not args.dry_run: print("Wrote reStructuredText files for each class to: %s" % args.output) else: if state.num_errors >= 2: print( - "%d errors were found in the class reference XML. Please check the messages above." % state.num_errors + "{}{} errors were found in the class reference XML. Please check the messages above.{}".format( + STYLES["red"], state.num_errors, STYLES["reset"] + ) ) else: - print("1 error was found in the class reference XML. Please check the messages above.") + print( + "{}1 error was found in the class reference XML. Please check the messages above.{}".format( + STYLES["red"], STYLES["reset"] + ) + ) exit(1) |