diff options
Diffstat (limited to 'doc')
26 files changed, 662 insertions, 375 deletions
diff --git a/doc/classes/AStarGrid2D.xml b/doc/classes/AStarGrid2D.xml new file mode 100644 index 0000000000..ae696eb468 --- /dev/null +++ b/doc/classes/AStarGrid2D.xml @@ -0,0 +1,116 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="AStarGrid2D" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + </brief_description> + <description> + </description> + <tutorials> + </tutorials> + <methods> + <method name="_compute_cost" qualifiers="virtual const"> + <return type="float" /> + <param index="0" name="from_id" type="Vector2i" /> + <param index="1" name="to_id" type="Vector2i" /> + <description> + </description> + </method> + <method name="_estimate_cost" qualifiers="virtual const"> + <return type="float" /> + <param index="0" name="from_id" type="Vector2i" /> + <param index="1" name="to_id" type="Vector2i" /> + <description> + </description> + </method> + <method name="clear"> + <return type="void" /> + <description> + </description> + </method> + <method name="get_id_path"> + <return type="PackedVector2Array" /> + <param index="0" name="from_id" type="Vector2i" /> + <param index="1" name="to_id" type="Vector2i" /> + <description> + </description> + </method> + <method name="get_point_path"> + <return type="PackedVector2Array" /> + <param index="0" name="from_id" type="Vector2i" /> + <param index="1" name="to_id" type="Vector2i" /> + <description> + </description> + </method> + <method name="is_dirty" qualifiers="const"> + <return type="bool" /> + <description> + </description> + </method> + <method name="is_in_bounds" qualifiers="const"> + <return type="bool" /> + <param index="0" name="x" type="int" /> + <param index="1" name="y" type="int" /> + <description> + </description> + </method> + <method name="is_in_boundsv" qualifiers="const"> + <return type="bool" /> + <param index="0" name="id" type="Vector2i" /> + <description> + </description> + </method> + <method name="is_point_solid" qualifiers="const"> + <return type="bool" /> + <param index="0" name="id" type="Vector2i" /> + <description> + </description> + </method> + <method name="set_point_solid"> + <return type="void" /> + <param index="0" name="id" type="Vector2i" /> + <param index="1" name="solid" type="bool" default="true" /> + <description> + </description> + </method> + <method name="update"> + <return type="void" /> + <description> + </description> + </method> + </methods> + <members> + <member name="cell_size" type="Vector2" setter="set_cell_size" getter="get_cell_size" default="Vector2(1, 1)"> + </member> + <member name="default_heuristic" type="int" setter="set_default_heuristic" getter="get_default_heuristic" enum="AStarGrid2D.Heuristic" default="0"> + </member> + <member name="diagonal_mode" type="int" setter="set_diagonal_mode" getter="get_diagonal_mode" enum="AStarGrid2D.DiagonalMode" default="0"> + </member> + <member name="jumping_enabled" type="bool" setter="set_jumping_enabled" getter="is_jumping_enabled" default="false"> + </member> + <member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)"> + </member> + <member name="size" type="Vector2i" setter="set_size" getter="get_size" default="Vector2i(0, 0)"> + </member> + </members> + <constants> + <constant name="HEURISTIC_EUCLIDEAN" value="0" enum="Heuristic"> + </constant> + <constant name="HEURISTIC_MANHATTAN" value="1" enum="Heuristic"> + </constant> + <constant name="HEURISTIC_OCTILE" value="2" enum="Heuristic"> + </constant> + <constant name="HEURISTIC_CHEBYSHEV" value="3" enum="Heuristic"> + </constant> + <constant name="HEURISTIC_MAX" value="4" enum="Heuristic"> + </constant> + <constant name="DIAGONAL_MODE_ALWAYS" value="0" enum="DiagonalMode"> + </constant> + <constant name="DIAGONAL_MODE_NEVER" value="1" enum="DiagonalMode"> + </constant> + <constant name="DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE" value="2" enum="DiagonalMode"> + </constant> + <constant name="DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES" value="3" enum="DiagonalMode"> + </constant> + <constant name="DIAGONAL_MODE_MAX" value="4" enum="DiagonalMode"> + </constant> + </constants> +</class> diff --git a/doc/classes/AnimationNodeTransition.xml b/doc/classes/AnimationNodeTransition.xml index d574bc044d..f6e2fc5eb2 100644 --- a/doc/classes/AnimationNodeTransition.xml +++ b/doc/classes/AnimationNodeTransition.xml @@ -40,12 +40,12 @@ </method> </methods> <members> + <member name="enabled_inputs" type="int" setter="set_enabled_inputs" getter="get_enabled_inputs" default="0"> + The number of enabled input ports for this node. + </member> <member name="from_start" type="bool" setter="set_from_start" getter="is_from_start" default="true"> If [code]true[/code], the destination animation is played back from the beginning when switched. </member> - <member name="input_count" type="int" setter="set_enabled_inputs" getter="get_enabled_inputs" default="0"> - The number of available input ports for this node. - </member> <member name="xfade_curve" type="Curve" setter="set_xfade_curve" getter="get_xfade_curve"> </member> <member name="xfade_time" type="float" setter="set_xfade_time" getter="get_xfade_time" default="0.0"> diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index 33a129a48e..2262c4fe47 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -82,7 +82,7 @@ The hashing scale for Alpha Hash. Recommended values between [code]0[/code] and [code]2[/code]. </member> <member name="alpha_scissor_threshold" type="float" setter="set_alpha_scissor_threshold" getter="get_alpha_scissor_threshold"> - Threshold at which the alpha scissor will discard values. + Threshold at which the alpha scissor will discard values. Higher values will result in more pixels being discarded. If the material becomes too opaque at a distance, try increasing [member alpha_scissor_threshold]. If the material disappears at a distance, try decreasing [member alpha_scissor_threshold]. </member> <member name="anisotropy" type="float" setter="set_anisotropy" getter="get_anisotropy" default="0.0"> The strength of the anisotropy effect. This is multiplied by [member anisotropy_flowmap]'s alpha channel if a texture is defined there and the texture contains an alpha channel. diff --git a/doc/classes/CPUParticles3D.xml b/doc/classes/CPUParticles3D.xml index 99fd0501fc..6b39c08b3f 100644 --- a/doc/classes/CPUParticles3D.xml +++ b/doc/classes/CPUParticles3D.xml @@ -123,13 +123,16 @@ Minimum particle animation speed. </member> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> - Each particle's initial color. To have particle display color in a [BaseMaterial3D] make sure to set [member BaseMaterial3D.vertex_color_use_as_albedo] to [code]true[/code]. + Each particle's initial color. + [b]Note:[/b] [member color] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color] will have no visible effect. </member> <member name="color_initial_ramp" type="Gradient" setter="set_color_initial_ramp" getter="get_color_initial_ramp"> Each particle's initial color will vary along this [GradientTexture1D] (multiplied with [member color]). + [b]Note:[/b] [member color_initial_ramp] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color_initial_ramp] will have no visible effect. </member> <member name="color_ramp" type="Gradient" setter="set_color_ramp" getter="get_color_ramp"> Each particle's color will vary along this [GradientTexture1D] over its lifetime (multiplied with [member color]). + [b]Note:[/b] [member color_ramp] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color_ramp] will have no visible effect. </member> <member name="damping_curve" type="Curve" setter="set_param_curve" getter="get_param_curve"> Damping will vary along this [Curve]. @@ -151,6 +154,7 @@ </member> <member name="emission_colors" type="PackedColorArray" setter="set_emission_colors" getter="get_emission_colors" default="PackedColorArray()"> Sets the [Color]s to modulate particles by when using [constant EMISSION_SHAPE_POINTS] or [constant EMISSION_SHAPE_DIRECTED_POINTS]. + [b]Note:[/b] [member emission_colors] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member emission_colors] will have no visible effect. </member> <member name="emission_normals" type="PackedVector3Array" setter="set_emission_normals" getter="get_emission_normals"> Sets the direction the particles will be emitted in when using [constant EMISSION_SHAPE_DIRECTED_POINTS]. diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml index 6838bdeb70..1fcaf6d866 100644 --- a/doc/classes/Callable.xml +++ b/doc/classes/Callable.xml @@ -75,6 +75,10 @@ <return type="void" /> <description> Calls the method represented by this [Callable] in deferred mode, i.e. during the idle frame. Arguments can be passed and should match the method's signature. + [codeblock] + func _ready(): + grab_focus.call_deferred() + [/codeblock] </description> </method> <method name="get_method" qualifiers="const"> diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index d1fdca5814..d8c1af0b3c 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -5,7 +5,7 @@ </brief_description> <description> Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. [CanvasItem] is extended by [Control] for anything GUI-related, and by [Node2D] for anything related to the 2D engine. - Any [CanvasItem] can draw. For this, [method update] is called by the engine, then [constant NOTIFICATION_DRAW] will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the [CanvasItem] are provided (see [code]draw_*[/code] functions). However, they can only be used inside [method _draw], its corresponding [method Object._notification] or methods connected to the [signal draw] signal. + Any [CanvasItem] can draw. For this, [method queue_redraw] is called by the engine, then [constant NOTIFICATION_DRAW] will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the [CanvasItem] are provided (see [code]draw_*[/code] functions). However, they can only be used inside [method _draw], its corresponding [method Object._notification] or methods connected to the [signal draw] signal. Canvas items are drawn in tree order. By default, children are on top of their parents so a root [CanvasItem] will be drawn behind everything. This behavior can be changed on a per-item basis. A [CanvasItem] can also be hidden, which will also hide its children. It provides many ways to change parameters such as modulation (for itself and its children) and self modulation (only for itself), as well as its blend mode. Ultimately, a transform notification can be requested, which will notify the node that its global position changed in case the parent tree changed. @@ -20,7 +20,7 @@ <method name="_draw" qualifiers="virtual"> <return type="void" /> <description> - Called when [CanvasItem] has been requested to redraw (when [method update] is called, either manually or by the engine). + Called when [CanvasItem] has been requested to redraw (after [method queue_redraw] is called, either manually or by the engine). Corresponds to the [constant NOTIFICATION_DRAW] notification in [method Object._notification]. </description> </method> @@ -500,6 +500,12 @@ Transformations issued by [param event]'s inputs are applied in local space instead of global space. </description> </method> + <method name="queue_redraw"> + <return type="void" /> + <description> + Queues the [CanvasItem] to redraw. During idle time, if [CanvasItem] is visible, [constant NOTIFICATION_DRAW] is sent and [method _draw] is called. This only occurs [b]once[/b] per frame, even if this method has been called multiple times. + </description> + </method> <method name="set_notify_local_transform"> <return type="void" /> <param index="0" name="enable" type="bool" /> @@ -520,12 +526,6 @@ Show the [CanvasItem] if it's currently hidden. This is equivalent to setting [member visible] to [code]true[/code]. For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead. </description> </method> - <method name="update"> - <return type="void" /> - <description> - Queues the [CanvasItem] to redraw. During idle time, if [CanvasItem] is visible, [constant NOTIFICATION_DRAW] is sent and [method _draw] is called. This only occurs [b]once[/b] per frame, even if this method has been called multiple times. - </description> - </method> </methods> <members> <member name="clip_children" type="bool" setter="set_clip_children" getter="is_clipping_children" default="false"> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 0e71dbd0b1..71798d2574 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -553,6 +553,7 @@ <return type="void" /> <description> Steal the focus from another control and become the focused control (see [member focus_mode]). + [b]Note[/b]: Using this method together with [method Callable.call_deferred] makes it more reliable, especially when called inside [method Node._ready]. </description> </method> <method name="has_focus" qualifiers="const"> diff --git a/doc/classes/Curve.xml b/doc/classes/Curve.xml index ae9add995b..20b9dafd0d 100644 --- a/doc/classes/Curve.xml +++ b/doc/classes/Curve.xml @@ -74,27 +74,27 @@ Returns the right tangent angle (in degrees) for the point at [param index]. </description> </method> - <method name="interpolate" qualifiers="const"> + <method name="remove_point"> + <return type="void" /> + <param index="0" name="index" type="int" /> + <description> + Removes the point at [code]index[/code] from the curve. + </description> + </method> + <method name="sample" qualifiers="const"> <return type="float" /> <param index="0" name="offset" type="float" /> <description> Returns the Y value for the point that would exist at the X position [param offset] along the curve. </description> </method> - <method name="interpolate_baked" qualifiers="const"> + <method name="sample_baked" qualifiers="const"> <return type="float" /> <param index="0" name="offset" type="float" /> <description> Returns the Y value for the point that would exist at the X position [param offset] along the curve using the baked cache. Bakes the curve's points if not already baked. </description> </method> - <method name="remove_point"> - <return type="void" /> - <param index="0" name="index" type="int" /> - <description> - Removes the point at [param index] from the curve. - </description> - </method> <method name="set_point_left_mode"> <return type="void" /> <param index="0" name="index" type="int" /> diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml index f15c0d74ca..cc4124d084 100644 --- a/doc/classes/Curve2D.xml +++ b/doc/classes/Curve2D.xml @@ -43,7 +43,7 @@ <return type="float" /> <param index="0" name="to_point" type="Vector2" /> <description> - Returns the closest offset to [param to_point]. This offset is meant to be used in [method interpolate_baked]. + Returns the closest offset to [param to_point]. This offset is meant to be used in [method sample_baked]. [param to_point] must be in this curve's local space. </description> </method> @@ -76,7 +76,14 @@ Returns the position of the vertex [param idx]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0)[/code]. </description> </method> - <method name="interpolate" qualifiers="const"> + <method name="remove_point"> + <return type="void" /> + <param index="0" name="idx" type="int" /> + <description> + Deletes the point [code]idx[/code] from the curve. Sends an error to the console if [code]idx[/code] is out of bounds. + </description> + </method> + <method name="sample" qualifiers="const"> <return type="Vector2" /> <param index="0" name="idx" type="int" /> <param index="1" name="t" type="float" /> @@ -85,7 +92,7 @@ If [param idx] is out of bounds it is truncated to the first or last vertex, and [param t] is ignored. If the curve has no points, the function sends an error to the console, and returns [code](0, 0)[/code]. </description> </method> - <method name="interpolate_baked" qualifiers="const"> + <method name="sample_baked" qualifiers="const"> <return type="Vector2" /> <param index="0" name="offset" type="float" /> <param index="1" name="cubic" type="bool" default="false" /> @@ -95,18 +102,11 @@ Cubic interpolation tends to follow the curves better, but linear is faster (and often, precise enough). </description> </method> - <method name="interpolatef" qualifiers="const"> + <method name="samplef" qualifiers="const"> <return type="Vector2" /> <param index="0" name="fofs" type="float" /> <description> - Returns the position at the vertex [param fofs]. It calls [method interpolate] using the integer part of [param fofs] as [code]idx[/code], and its fractional part as [code]t[/code]. - </description> - </method> - <method name="remove_point"> - <return type="void" /> - <param index="0" name="idx" type="int" /> - <description> - Deletes the point [param idx] from the curve. Sends an error to the console if [param idx] is out of bounds. + Returns the position at the vertex [param fofs]. It calls [method sample] using the integer part of [param fofs] as [code]idx[/code], and its fractional part as [code]t[/code]. </description> </method> <method name="set_point_in"> diff --git a/doc/classes/Curve3D.xml b/doc/classes/Curve3D.xml index 0843453820..3e4e05f51a 100644 --- a/doc/classes/Curve3D.xml +++ b/doc/classes/Curve3D.xml @@ -56,7 +56,7 @@ <return type="float" /> <param index="0" name="to_point" type="Vector3" /> <description> - Returns the closest offset to [param to_point]. This offset is meant to be used in [method interpolate_baked] or [method interpolate_baked_up_vector]. + Returns the closest offset to [param to_point]. This offset is meant to be used in [method sample_baked] or [method sample_baked_up_vector]. [param to_point] must be in this curve's local space. </description> </method> @@ -96,7 +96,14 @@ Returns the tilt angle in radians for the point [param idx]. If the index is out of bounds, the function sends an error to the console, and returns [code]0[/code]. </description> </method> - <method name="interpolate" qualifiers="const"> + <method name="remove_point"> + <return type="void" /> + <param index="0" name="idx" type="int" /> + <description> + Deletes the point [code]idx[/code] from the curve. Sends an error to the console if [code]idx[/code] is out of bounds. + </description> + </method> + <method name="sample" qualifiers="const"> <return type="Vector3" /> <param index="0" name="idx" type="int" /> <param index="1" name="t" type="float" /> @@ -105,7 +112,7 @@ If [param idx] is out of bounds it is truncated to the first or last vertex, and [param t] is ignored. If the curve has no points, the function sends an error to the console, and returns [code](0, 0, 0)[/code]. </description> </method> - <method name="interpolate_baked" qualifiers="const"> + <method name="sample_baked" qualifiers="const"> <return type="Vector3" /> <param index="0" name="offset" type="float" /> <param index="1" name="cubic" type="bool" default="false" /> @@ -115,7 +122,7 @@ Cubic interpolation tends to follow the curves better, but linear is faster (and often, precise enough). </description> </method> - <method name="interpolate_baked_up_vector" qualifiers="const"> + <method name="sample_baked_up_vector" qualifiers="const"> <return type="Vector3" /> <param index="0" name="offset" type="float" /> <param index="1" name="apply_tilt" type="bool" default="false" /> @@ -125,18 +132,11 @@ If the curve has no up vectors, the function sends an error to the console, and returns [code](0, 1, 0)[/code]. </description> </method> - <method name="interpolatef" qualifiers="const"> + <method name="samplef" qualifiers="const"> <return type="Vector3" /> <param index="0" name="fofs" type="float" /> <description> - Returns the position at the vertex [param fofs]. It calls [method interpolate] using the integer part of [param fofs] as [code]idx[/code], and its fractional part as [code]t[/code]. - </description> - </method> - <method name="remove_point"> - <return type="void" /> - <param index="0" name="idx" type="int" /> - <description> - Deletes the point [param idx] from the curve. Sends an error to the console if [param idx] is out of bounds. + Returns the position at the vertex [param fofs]. It calls [method sample] using the integer part of [param fofs] as [code]idx[/code], and its fractional part as [code]t[/code]. </description> </method> <method name="set_point_in"> diff --git a/doc/classes/EditorProperty.xml b/doc/classes/EditorProperty.xml index 67204f2a15..7bac4bf7ac 100644 --- a/doc/classes/EditorProperty.xml +++ b/doc/classes/EditorProperty.xml @@ -105,6 +105,8 @@ <signal name="property_changed"> <param index="0" name="property" type="StringName" /> <param index="1" name="value" type="Variant" /> + <param index="2" name="field" type="StringName" /> + <param index="3" name="changing" type="bool" /> <description> Do not emit this manually, use the [method emit_changed] method instead. </description> diff --git a/doc/classes/EditorVCSInterface.xml b/doc/classes/EditorVCSInterface.xml index 89ba79f7d9..cca6a0591f 100644 --- a/doc/classes/EditorVCSInterface.xml +++ b/doc/classes/EditorVCSInterface.xml @@ -1,97 +1,276 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="EditorVCSInterface" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Version Control System (VCS) interface which reads and writes to the local VCS in use. + Version Control System (VCS) interface, which reads and writes to the local VCS in use. </brief_description> <description> - Used by the editor to display VCS extracted information in the editor. The implementation of this API is included in VCS addons, which are essentially GDExtension plugins that need to be put into the project folder. These VCS addons are scripts which are attached (on demand) to the object instance of [code]EditorVCSInterface[/code]. All the functions listed below, instead of performing the task themselves, they call the internally defined functions in the VCS addons to provide a plug-n-play experience. + Defines the API that the editor uses to extract information from the underlying VCS. The implementation of this API is included in VCS plugins, which are GDExtension plugins that inherit [EditorVCSInterface] and are attached (on demand) to the singleton instance of [EditorVCSInterface]. Instead of performing the task themselves, all the virtual functions listed below are calling the internally overridden functions in the VCS plugins to provide a plug-n-play experience. A custom VCS plugin is supposed to inherit from [EditorVCSInterface] and override each of these virtual functions. </description> <tutorials> </tutorials> <methods> - <method name="commit"> + <method name="_checkout_branch" qualifiers="virtual"> + <return type="bool" /> + <param index="0" name="branch_name" type="String" /> + <description> + Checks out a [code]branch_name[/code] in the VCS. + </description> + </method> + <method name="_commit" qualifiers="virtual"> <return type="void" /> <param index="0" name="msg" type="String" /> <description> - Creates a version commit if the addon is initialized, else returns without doing anything. Uses the files which have been staged previously, with the commit message set to a value as provided as in the argument. + Commits the currently staged changes and applies the commit [code]msg[/code] to the resulting commit. </description> </method> - <method name="get_file_diff"> - <return type="Dictionary[]" /> + <method name="_create_branch" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="branch_name" type="String" /> + <description> + Creates a new branch named [code]branch_name[/code] in the VCS. + </description> + </method> + <method name="_create_remote" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="remote_name" type="String" /> + <param index="1" name="remote_url" type="String" /> + <description> + Creates a new remote destination with name [code]remote_name[/code] and points it to [code]remote_url[/code]. This can be an HTTPS remote or an SSH remote. + </description> + </method> + <method name="_discard_file" qualifiers="virtual"> + <return type="void" /> <param index="0" name="file_path" type="String" /> <description> - Returns an [Array] of [Dictionary] objects containing the diff output from the VCS in use, if a VCS addon is initialized, else returns an empty [Array] object. The diff contents also consist of some contextual lines which provide context to the observed line change in the file. - Each [Dictionary] object has the line diff contents under the keys: - - [code]"content"[/code] to store a [String] containing the line contents - - [code]"status"[/code] to store a [String] which contains [code]"+"[/code] in case the content is a line addition but it stores a [code]"-"[/code] in case of deletion and an empty string in the case the line content is neither an addition nor a deletion. - - [code]"new_line_number"[/code] to store an integer containing the new line number of the line content. - - [code]"line_count"[/code] to store an integer containing the number of lines in the line content. - - [code]"old_line_number"[/code] to store an integer containing the old line number of the line content. - - [code]"offset"[/code] to store the offset of the line change since the first contextual line content. + Discards the changes made in a file present at [code]file_path[/code]. </description> </method> - <method name="get_modified_files_data"> - <return type="Dictionary" /> + <method name="_fetch" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="remote" type="String" /> <description> - Returns a [Dictionary] containing the path of the detected file change mapped to an integer signifying what kind of change the corresponding file has experienced. - The following integer values are being used to signify that the detected file is: - - [code]0[/code]: New to the VCS working directory - - [code]1[/code]: Modified - - [code]2[/code]: Renamed - - [code]3[/code]: Deleted - - [code]4[/code]: Typechanged + Fetches new changes from the remote, but doesn't write changes to the current working directory. Equivalent to [code]git fetch[/code]. </description> </method> - <method name="get_project_name"> + <method name="_get_branch_list" qualifiers="virtual"> + <return type="Array" /> + <description> + Gets an instance of an [Array] of [String]s containing available branch names in the VCS. + </description> + </method> + <method name="_get_current_branch_name" qualifiers="virtual"> <return type="String" /> <description> - Returns the project name of the VCS working directory. + Gets the current branch name defined in the VCS. + </description> + </method> + <method name="_get_diff" qualifiers="virtual"> + <return type="Dictionary[]" /> + <param index="0" name="identifier" type="String" /> + <param index="1" name="area" type="int" /> + <description> + Returns an array of [Dictionary] items (see [method create_diff_file], [method create_diff_hunk], [method create_diff_line], [method add_line_diffs_into_diff_hunk] and [method add_diff_hunks_into_diff_file]), each containing information about a diff. If [code]identifier[/code] is a file path, returns a file diff, and if it is a commit identifier, then returns a commit diff. + </description> + </method> + <method name="_get_line_diff" qualifiers="virtual"> + <return type="Array" /> + <param index="0" name="file_path" type="String" /> + <param index="1" name="text" type="String" /> + <description> + Returns an [Array] of [Dictionary] items (see [method create_diff_hunk]), each containing a line diff between a file at [code]file_path[/code] and the [code]text[/code] which is passed in. + </description> + </method> + <method name="_get_modified_files_data" qualifiers="virtual"> + <return type="Array" /> + <description> + Returns an [Array] of [Dictionary] items (see [method create_status_file]), each containing the status data of every modified file in the project folder. + </description> + </method> + <method name="_get_previous_commits" qualifiers="virtual"> + <return type="Array" /> + <param index="0" name="max_commits" type="int" /> + <description> + Returns an [Array] of [Dictionary] items (see [method create_commit]), each containing the data for a past commit. </description> </method> - <method name="get_vcs_name"> + <method name="_get_remotes" qualifiers="virtual"> + <return type="Array" /> + <description> + Returns an [Array] of [String]s, each containing the name of a remote configured in the VCS. + </description> + </method> + <method name="_get_vcs_name" qualifiers="virtual"> <return type="String" /> <description> - Returns the name of the VCS if the VCS has been initialized, else return an empty string. + Returns the name of the underlying VCS provider. </description> </method> - <method name="initialize"> + <method name="_initialize" qualifiers="virtual"> <return type="bool" /> - <param index="0" name="project_root_path" type="String" /> + <param index="0" name="project_path" type="String" /> <description> - Initializes the VCS addon if not already. Uses the argument value as the path to the working directory of the project. Creates the initial commit if required. Returns [code]true[/code] if no failure occurs, else returns [code]false[/code]. + Initializes the VCS plugin when called from the editor. Returns whether or not the plugin was successfully initialized. A VCS project is initialized at [code]project_path[/code]. </description> </method> - <method name="is_addon_ready"> - <return type="bool" /> + <method name="_pull" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="remote" type="String" /> <description> - Returns [code]true[/code] if the addon is ready to respond to function calls, else returns [code]false[/code]. + Pulls changes from the remote. This can give rise to merge conflicts. </description> </method> - <method name="is_vcs_initialized"> - <return type="bool" /> + <method name="_push" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="remote" type="String" /> + <param index="1" name="force" type="bool" /> + <description> + Pushes changes to the [code]remote[/code]. Optionally, if [code]force[/code] is set to true, a force push will override the change history already present on the remote. + </description> + </method> + <method name="_remove_branch" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="branch_name" type="String" /> <description> - Returns [code]true[/code] if the VCS addon has been initialized, else returns [code]false[/code]. + Remove a branch from the local VCS. </description> </method> - <method name="shut_down"> + <method name="_remove_remote" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="remote_name" type="String" /> + <description> + Remove a remote from the local VCS. + </description> + </method> + <method name="_set_credentials" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="username" type="String" /> + <param index="1" name="password" type="String" /> + <param index="2" name="ssh_public_key_path" type="String" /> + <param index="3" name="ssh_private_key_path" type="String" /> + <param index="4" name="ssh_passphrase" type="String" /> + <description> + Set user credentials in the underlying VCS. [code]username[/code] and [code]password[/code] are used only during HTTPS authentication unless not already mentioned in the remote URL. [code]ssh_public_key_path[/code], [code]ssh_private_key_path[/code], and [code]ssh_passphrase[/code] are only used during SSH authentication. + </description> + </method> + <method name="_shut_down" qualifiers="virtual"> <return type="bool" /> <description> - Shuts down the VCS addon to allow cleanup code to run on call. Returns [code]true[/code] is no failure occurs, else returns [code]false[/code]. + Shuts down VCS plugin instance. Called when the user either closes the editor or shuts down the VCS plugin through the editor UI. </description> </method> - <method name="stage_file"> + <method name="_stage_file" qualifiers="virtual"> <return type="void" /> <param index="0" name="file_path" type="String" /> <description> - Stages the file which should be committed when [method EditorVCSInterface.commit] is called. Argument should contain the absolute path. + Stages the file present at [code]file_path[/code] to the staged area. </description> </method> - <method name="unstage_file"> + <method name="_unstage_file" qualifiers="virtual"> <return type="void" /> <param index="0" name="file_path" type="String" /> <description> - Unstages the file which was staged previously to be committed, so that it is no longer committed when [method EditorVCSInterface.commit] is called. Argument should contain the absolute path. + Unstages the file present at [code]file_path[/code] from the staged area to the unstaged area. + </description> + </method> + <method name="add_diff_hunks_into_diff_file"> + <return type="Dictionary" /> + <param index="0" name="diff_file" type="Dictionary" /> + <param index="1" name="diff_hunks" type="Array" /> + <description> + Helper function to add an array of [code]diff_hunks[/code] into a [code]diff_file[/code]. + </description> + </method> + <method name="add_line_diffs_into_diff_hunk"> + <return type="Dictionary" /> + <param index="0" name="diff_hunk" type="Dictionary" /> + <param index="1" name="line_diffs" type="Array" /> + <description> + Helper function to add an array of [code]line_diffs[/code] into a [code]diff_hunk[/code]. + </description> + </method> + <method name="create_commit"> + <return type="Dictionary" /> + <param index="0" name="msg" type="String" /> + <param index="1" name="author" type="String" /> + <param index="2" name="id" type="String" /> + <param index="3" name="unix_timestamp" type="int" /> + <param index="4" name="offset_minutes" type="int" /> + <description> + Helper function to create a commit [Dictionary] item. [code]msg[/code] is the commit message of the commit. [code]author[/code] is a single human-readable string containing all the author's details, e.g. the email and name configured in the VCS. [code]id[/code] is the identifier of the commit, in whichever format your VCS may provide an identifier to commits. [code]unix_timestamp[/code] is the UTC Unix timestamp of when the commit was created. [code]offset_minutes[/code] is the timezone offset in minutes, recorded from the system timezone where the commit was created. + </description> + </method> + <method name="create_diff_file"> + <return type="Dictionary" /> + <param index="0" name="new_file" type="String" /> + <param index="1" name="old_file" type="String" /> + <description> + Helper function to create a [code]Dictionary[/code] for storing old and new diff file paths. + </description> + </method> + <method name="create_diff_hunk"> + <return type="Dictionary" /> + <param index="0" name="old_start" type="int" /> + <param index="1" name="new_start" type="int" /> + <param index="2" name="old_lines" type="int" /> + <param index="3" name="new_lines" type="int" /> + <description> + Helper function to create a [code]Dictionary[/code] for storing diff hunk data. [code]old_start[/code] is the starting line number in old file. [code]new_start[/code] is the starting line number in new file. [code]old_lines[/code] is the number of lines in the old file. [code]new_lines[/code] is the number of lines in the new file. + </description> + </method> + <method name="create_diff_line"> + <return type="Dictionary" /> + <param index="0" name="new_line_no" type="int" /> + <param index="1" name="old_line_no" type="int" /> + <param index="2" name="content" type="String" /> + <param index="3" name="status" type="String" /> + <description> + Helper function to create a [code]Dictionary[/code] for storing a line diff. [code]new_line_no[/code] is the line number in the new file (can be [code]-1[/code] if the line is deleted). [code]old_line_no[/code] is the line number in the old file (can be [code]-1[/code] if the line is added). [code]content[/code] is the diff text. [code]status[/code] is a single character string which stores the line origin. + </description> + </method> + <method name="create_status_file"> + <return type="Dictionary" /> + <param index="0" name="file_path" type="String" /> + <param index="1" name="change_type" type="int" enum="EditorVCSInterface.ChangeType" /> + <param index="2" name="area" type="int" enum="EditorVCSInterface.TreeArea" /> + <description> + Helper function to create a [code]Dictionary[/code] used by editor to read the status of a file. + </description> + </method> + <method name="popup_error"> + <return type="void" /> + <param index="0" name="msg" type="String" /> + <description> + Pops up an error message in the edior which is shown as coming from the underlying VCS. Use this to show VCS specific error messages. </description> </method> </methods> + <constants> + <constant name="CHANGE_TYPE_NEW" value="0" enum="ChangeType"> + A new file has been added. + </constant> + <constant name="CHANGE_TYPE_MODIFIED" value="1" enum="ChangeType"> + An earlier added file has been modified. + </constant> + <constant name="CHANGE_TYPE_RENAMED" value="2" enum="ChangeType"> + An earlier added file has been renamed. + </constant> + <constant name="CHANGE_TYPE_DELETED" value="3" enum="ChangeType"> + An earlier added file has been deleted. + </constant> + <constant name="CHANGE_TYPE_TYPECHANGE" value="4" enum="ChangeType"> + An earlier added file has been typechanged. + </constant> + <constant name="CHANGE_TYPE_UNMERGED" value="5" enum="ChangeType"> + A file is left unmerged. + </constant> + <constant name="TREE_AREA_COMMIT" value="0" enum="TreeArea"> + A commit is encountered from the commit area. + </constant> + <constant name="TREE_AREA_STAGED" value="1" enum="TreeArea"> + A file is encountered from the staged area. + </constant> + <constant name="TREE_AREA_UNSTAGED" value="2" enum="TreeArea"> + A file is encountered from the unstaged area. + </constant> + </constants> </class> diff --git a/doc/classes/Gradient.xml b/doc/classes/Gradient.xml index f081174b67..33f0a7979a 100644 --- a/doc/classes/Gradient.xml +++ b/doc/classes/Gradient.xml @@ -38,13 +38,6 @@ Returns the number of colors in the gradient. </description> </method> - <method name="interpolate"> - <return type="Color" /> - <param index="0" name="offset" type="float" /> - <description> - Returns the interpolated color specified by [param offset]. - </description> - </method> <method name="remove_point"> <return type="void" /> <param index="0" name="point" type="int" /> @@ -58,6 +51,13 @@ Reverses/mirrors the gradient. </description> </method> + <method name="sample"> + <return type="Color" /> + <param index="0" name="offset" type="float" /> + <description> + Returns the interpolated color specified by [code]offset[/code]. + </description> + </method> <method name="set_color"> <return type="void" /> <param index="0" name="point" type="int" /> diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index 80ff83ec46..cc8484d9fa 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -80,6 +80,10 @@ <member name="light_specular" type="float" setter="set_param" getter="get_param" default="0.5"> The intensity of the specular blob in objects affected by the light. At [code]0[/code], the light becomes a pure diffuse light. When not baking emission, this can be used to avoid unrealistic reflections when placing lights above an emissive surface. </member> + <member name="light_volumetric_fog_energy" type="float" setter="set_param" getter="get_param" default="1.0"> + Secondary multiplier multiplied with [member light_energy] then used with the [Environment]'s volumetric fog (if enabled). If set to [code]0.0[/code], computing volumetric fog will be skipped for this light, which can improve performance for large amounts of lights when volumetric fog is enabled. + [b]Note:[/b] To prevent short-lived dynamic light effects from poorly interacting with volumetric fog, lights used in those effects should have [member light_volumetric_fog_energy] set to [code]0.0[/code] unless [member Environment.volumetric_fog_temporal_reprojection_enabled] is disabled (or unless the reprojection amount is significantly lowered). + </member> <member name="shadow_bias" type="float" setter="set_param" getter="get_param" default="0.1"> Used to adjust shadow appearance. Too small a value results in self-shadowing ("shadow acne"), while too large a value causes shadows to separate from casters ("peter-panning"). Adjust as needed. </member> @@ -89,8 +93,6 @@ <member name="shadow_enabled" type="bool" setter="set_shadow" getter="has_shadow" default="false"> If [code]true[/code], the light will cast real-time shadows. This has a significant performance cost. Only enable shadow rendering when it makes a noticeable difference in the scene's appearance, and consider using [member distance_fade_enabled] to hide the light when far away from the [Camera3D]. </member> - <member name="shadow_fog_fade" type="float" setter="set_param" getter="get_param" default="0.1"> - </member> <member name="shadow_normal_bias" type="float" setter="set_param" getter="get_param" default="1.0"> Offsets the lookup into the shadow map by the object's normal. This can be used to reduce self-shadowing artifacts without using [member shadow_bias]. In practice, this value should be tweaked along with [member shadow_bias] to reduce artifacts as much as possible. </member> @@ -110,57 +112,57 @@ <constant name="PARAM_INDIRECT_ENERGY" value="1" enum="Param"> Constant for accessing [member light_indirect_energy]. </constant> - <constant name="PARAM_SPECULAR" value="2" enum="Param"> + <constant name="PARAM_VOLUMETRIC_FOG_ENERGY" value="2" enum="Param"> + Constant for accessing [member light_volumetric_fog_energy]. + </constant> + <constant name="PARAM_SPECULAR" value="3" enum="Param"> Constant for accessing [member light_specular]. </constant> - <constant name="PARAM_RANGE" value="3" enum="Param"> + <constant name="PARAM_RANGE" value="4" enum="Param"> Constant for accessing [member OmniLight3D.omni_range] or [member SpotLight3D.spot_range]. </constant> - <constant name="PARAM_SIZE" value="4" enum="Param"> + <constant name="PARAM_SIZE" value="5" enum="Param"> Constant for accessing [member light_size]. </constant> - <constant name="PARAM_ATTENUATION" value="5" enum="Param"> + <constant name="PARAM_ATTENUATION" value="6" enum="Param"> Constant for accessing [member OmniLight3D.omni_attenuation] or [member SpotLight3D.spot_attenuation]. </constant> - <constant name="PARAM_SPOT_ANGLE" value="6" enum="Param"> + <constant name="PARAM_SPOT_ANGLE" value="7" enum="Param"> Constant for accessing [member SpotLight3D.spot_angle]. </constant> - <constant name="PARAM_SPOT_ATTENUATION" value="7" enum="Param"> + <constant name="PARAM_SPOT_ATTENUATION" value="8" enum="Param"> Constant for accessing [member SpotLight3D.spot_angle_attenuation]. </constant> - <constant name="PARAM_SHADOW_MAX_DISTANCE" value="8" enum="Param"> + <constant name="PARAM_SHADOW_MAX_DISTANCE" value="9" enum="Param"> Constant for accessing [member DirectionalLight3D.directional_shadow_max_distance]. </constant> - <constant name="PARAM_SHADOW_SPLIT_1_OFFSET" value="9" enum="Param"> + <constant name="PARAM_SHADOW_SPLIT_1_OFFSET" value="10" enum="Param"> Constant for accessing [member DirectionalLight3D.directional_shadow_split_1]. </constant> - <constant name="PARAM_SHADOW_SPLIT_2_OFFSET" value="10" enum="Param"> + <constant name="PARAM_SHADOW_SPLIT_2_OFFSET" value="11" enum="Param"> Constant for accessing [member DirectionalLight3D.directional_shadow_split_2]. </constant> - <constant name="PARAM_SHADOW_SPLIT_3_OFFSET" value="11" enum="Param"> + <constant name="PARAM_SHADOW_SPLIT_3_OFFSET" value="12" enum="Param"> Constant for accessing [member DirectionalLight3D.directional_shadow_split_3]. </constant> - <constant name="PARAM_SHADOW_FADE_START" value="12" enum="Param"> + <constant name="PARAM_SHADOW_FADE_START" value="13" enum="Param"> Constant for accessing [member DirectionalLight3D.directional_shadow_fade_start]. </constant> - <constant name="PARAM_SHADOW_NORMAL_BIAS" value="13" enum="Param"> + <constant name="PARAM_SHADOW_NORMAL_BIAS" value="14" enum="Param"> Constant for accessing [member shadow_normal_bias]. </constant> - <constant name="PARAM_SHADOW_BIAS" value="14" enum="Param"> + <constant name="PARAM_SHADOW_BIAS" value="15" enum="Param"> Constant for accessing [member shadow_bias]. </constant> - <constant name="PARAM_SHADOW_PANCAKE_SIZE" value="15" enum="Param"> + <constant name="PARAM_SHADOW_PANCAKE_SIZE" value="16" enum="Param"> Constant for accessing [member DirectionalLight3D.directional_shadow_pancake_size]. </constant> - <constant name="PARAM_SHADOW_OPACITY" value="16" enum="Param"> + <constant name="PARAM_SHADOW_OPACITY" value="17" enum="Param"> Constant for accessing [member shadow_opacity]. </constant> - <constant name="PARAM_SHADOW_BLUR" value="17" enum="Param"> + <constant name="PARAM_SHADOW_BLUR" value="18" enum="Param"> Constant for accessing [member shadow_blur]. </constant> - <constant name="PARAM_SHADOW_VOLUMETRIC_FOG_FADE" value="18" enum="Param"> - Constant for accessing [member shadow_fog_fade]. - </constant> <constant name="PARAM_TRANSMITTANCE_BIAS" value="19" enum="Param"> Constant for accessing [member shadow_transmittance_bias]. </constant> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index b882425960..87edc7de0a 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -856,8 +856,8 @@ <constant name="NOTIFICATION_UNPARENTED" value="19"> Notification received when a node is unparented (parent removed it from the list of children). </constant> - <constant name="NOTIFICATION_INSTANCED" value="20"> - Notification received when the node is instantiated. + <constant name="NOTIFICATION_SCENE_INSTANTIATED" value="20"> + Notification received by scene owner when its scene is instantiated. </constant> <constant name="NOTIFICATION_DRAG_BEGIN" value="21"> Notification received when a drag operation begins. All nodes receive this notification, not only the dragged one. diff --git a/doc/classes/PackedScene.xml b/doc/classes/PackedScene.xml index 754d3ac73d..97595a6984 100644 --- a/doc/classes/PackedScene.xml +++ b/doc/classes/PackedScene.xml @@ -92,7 +92,7 @@ <return type="Node" /> <param index="0" name="edit_state" type="int" enum="PackedScene.GenEditState" default="0" /> <description> - Instantiates the scene's node hierarchy. Triggers child scene instantiation(s). Triggers a [constant Node.NOTIFICATION_INSTANCED] notification on the root node. + Instantiates the scene's node hierarchy. Triggers child scene instantiation(s). Triggers a [constant Node.NOTIFICATION_SCENE_INSTANTIATED] notification on the root node. </description> </method> <method name="pack"> diff --git a/doc/classes/ParticleProcessMaterial.xml b/doc/classes/ParticleProcessMaterial.xml index 1526658eed..a41207e9b3 100644 --- a/doc/classes/ParticleProcessMaterial.xml +++ b/doc/classes/ParticleProcessMaterial.xml @@ -129,13 +129,16 @@ Should collision take scale into account. </member> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> - Each particle's initial color. If the [GPUParticles2D]'s [code]texture[/code] is defined, it will be multiplied by this color. To have particle display color in a [BaseMaterial3D] make sure to set [member BaseMaterial3D.vertex_color_use_as_albedo] to [code]true[/code]. + Each particle's initial color. If the [GPUParticles2D]'s [code]texture[/code] is defined, it will be multiplied by this color. + [b]Note:[/b] [member color] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color] will have no visible effect. </member> <member name="color_initial_ramp" type="Texture2D" setter="set_color_initial_ramp" getter="get_color_initial_ramp"> Each particle's initial color will vary along this [GradientTexture1D] (multiplied with [member color]). + [b]Note:[/b] [member color_initial_ramp] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color_initial_ramp] will have no visible effect. </member> <member name="color_ramp" type="Texture2D" setter="set_color_ramp" getter="get_color_ramp"> Each particle's color will vary along this [GradientTexture1D] over its lifetime (multiplied with [member color]). + [b]Note:[/b] [member color_ramp] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color_ramp] will have no visible effect. </member> <member name="damping_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture"> Damping will vary along this [CurveTexture]. @@ -154,6 +157,7 @@ </member> <member name="emission_color_texture" type="Texture2D" setter="set_emission_color_texture" getter="get_emission_color_texture"> Particle color will be modulated by color determined by sampling this texture at the same point as the [member emission_point_texture]. + [b]Note:[/b] [member emission_color_texture] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member emission_color_texture] will have no visible effect. </member> <member name="emission_normal_texture" type="Texture2D" setter="set_emission_normal_texture" getter="get_emission_normal_texture"> Particle velocity and rotation will be set by sampling this texture at the same point as the [member emission_point_texture]. Used only in [constant EMISSION_SHAPE_DIRECTED_POINTS]. Can be created automatically from mesh or node by selecting "Create Emission Points from Mesh/Node" under the "Particles" tool in the toolbar. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 8f749f3a37..e8e8ca3725 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -100,7 +100,7 @@ # `path` will contain the absolute path to `hello.txt` next to the executable. # This is *not* identical to using `ProjectSettings.globalize_path()` with a `res://` path, # but is close enough in spirit. - path = OS.get_executable_path().get_base_dir().plus_file("hello.txt") + path = OS.get_executable_path().get_base_dir().path_join("hello.txt") [/codeblock] </description> </method> @@ -1639,8 +1639,11 @@ </member> <member name="rendering/2d/snap/snap_2d_vertices_to_pixel" type="bool" setter="" getter="" default="false"> </member> - <member name="rendering/anti_aliasing/quality/msaa" type="int" setter="" getter="" default="0"> - Sets the number of MSAA samples to use (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. See also bilinear scaling 3d [member rendering/scaling_3d/mode] for supersampling, which provides higher quality but is much more expensive. + <member name="rendering/anti_aliasing/quality/msaa_2d" type="int" setter="" getter="" default="0"> + Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. This has no effect on shader-induced aliasing or texture aliasing. + </member> + <member name="rendering/anti_aliasing/quality/msaa_3d" type="int" setter="" getter="" default="0"> + Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. See also bilinear scaling 3d [member rendering/scaling_3d/mode] for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. </member> <member name="rendering/anti_aliasing/quality/screen_space_aa" type="int" setter="" getter="" default="0"> Sets the screen-space antialiasing mode for the default screen [Viewport]. Screen-space antialiasing works by selectively blurring edges in a post-process shader. It differs from MSAA which takes multiple coverage samples while rendering objects. Screen-space AA methods are typically faster than MSAA and will smooth out specular aliasing, but tend to make scenes appear blurry. The blurriness is partially counteracted by automatically using a negative mipmap LOD bias (see [member rendering/textures/default_filters/texture_mipmap_bias]). @@ -1874,7 +1877,7 @@ Sets the scaling 3D mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible. </member> <member name="rendering/scaling_3d/scale" type="float" setter="" getter="" default="1.0"> - Scales the 3D render buffer based on the viewport size uses an image filter specified in [member rendering/scaling_3d/mode] to scale the output image to the full viewport size. Values lower than [code]1.0[/code] can be used to speed up 3D rendering at the cost of quality (undersampling). Values greater than [code]1.0[/code] are only valid for bilinear mode and can be used to improve 3D rendering quality at a high performance cost (supersampling). See also [member rendering/anti_aliasing/quality/msaa] for multi-sample antialiasing, which is significantly cheaper but only smoothens the edges of polygons. + Scales the 3D render buffer based on the viewport size uses an image filter specified in [member rendering/scaling_3d/mode] to scale the output image to the full viewport size. Values lower than [code]1.0[/code] can be used to speed up 3D rendering at the cost of quality (undersampling). Values greater than [code]1.0[/code] are only valid for bilinear mode and can be used to improve 3D rendering quality at a high performance cost (supersampling). See also [member rendering/anti_aliasing/quality/msaa_3d] for multi-sample antialiasing, which is significantly cheaper but only smooths the edges of polygons. </member> <member name="rendering/shader_compiler/shader_cache/compress" type="bool" setter="" getter="" default="true"> </member> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 639db6b3b5..310e2334fb 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -3208,12 +3208,20 @@ <description> </description> </method> - <method name="viewport_set_msaa"> + <method name="viewport_set_msaa_2d"> <return type="void" /> <param index="0" name="viewport" type="RID" /> <param index="1" name="msaa" type="int" enum="RenderingServer.ViewportMSAA" /> <description> - Sets the anti-aliasing mode. See [enum ViewportMSAA] for options. + Sets the multisample anti-aliasing mode for 2D/Canvas. See [enum ViewportMSAA] for options. + </description> + </method> + <method name="viewport_set_msaa_3d"> + <return type="void" /> + <param index="0" name="viewport" type="RID" /> + <param index="1" name="msaa" type="int" enum="RenderingServer.ViewportMSAA" /> + <description> + Sets the multisample anti-aliasing mode for 3D. See [enum ViewportMSAA] for options. </description> </method> <method name="viewport_set_occlusion_culling_build_quality"> @@ -3784,61 +3792,62 @@ Is a spot light. </constant> <constant name="LIGHT_PARAM_ENERGY" value="0" enum="LightParam"> - The light's energy. + The light's energy multiplier. </constant> <constant name="LIGHT_PARAM_INDIRECT_ENERGY" value="1" enum="LightParam"> The light's indirect energy multiplier (final indirect energy is [constant LIGHT_PARAM_ENERGY] * [constant LIGHT_PARAM_INDIRECT_ENERGY]). </constant> - <constant name="LIGHT_PARAM_SPECULAR" value="2" enum="LightParam"> + <constant name="LIGHT_PARAM_VOLUMETRIC_FOG_ENERGY" value="2" enum="LightParam"> + The light's volumetric fog energy multiplier (final volumetric fog energy is [constant LIGHT_PARAM_ENERGY] * [constant LIGHT_PARAM_VOLUMETRIC_FOG_ENERGY]). + </constant> + <constant name="LIGHT_PARAM_SPECULAR" value="3" enum="LightParam"> The light's influence on specularity. </constant> - <constant name="LIGHT_PARAM_RANGE" value="3" enum="LightParam"> + <constant name="LIGHT_PARAM_RANGE" value="4" enum="LightParam"> The light's range. </constant> - <constant name="LIGHT_PARAM_SIZE" value="4" enum="LightParam"> + <constant name="LIGHT_PARAM_SIZE" value="5" enum="LightParam"> The size of the light when using spot light or omni light. The angular size of the light when using directional light. </constant> - <constant name="LIGHT_PARAM_ATTENUATION" value="5" enum="LightParam"> + <constant name="LIGHT_PARAM_ATTENUATION" value="6" enum="LightParam"> The light's attenuation. </constant> - <constant name="LIGHT_PARAM_SPOT_ANGLE" value="6" enum="LightParam"> + <constant name="LIGHT_PARAM_SPOT_ANGLE" value="7" enum="LightParam"> The spotlight's angle. </constant> - <constant name="LIGHT_PARAM_SPOT_ATTENUATION" value="7" enum="LightParam"> + <constant name="LIGHT_PARAM_SPOT_ATTENUATION" value="8" enum="LightParam"> The spotlight's attenuation. </constant> - <constant name="LIGHT_PARAM_SHADOW_MAX_DISTANCE" value="8" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_MAX_DISTANCE" value="9" enum="LightParam"> Max distance that shadows will be rendered. </constant> - <constant name="LIGHT_PARAM_SHADOW_SPLIT_1_OFFSET" value="9" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_SPLIT_1_OFFSET" value="10" enum="LightParam"> Proportion of shadow atlas occupied by the first split. </constant> - <constant name="LIGHT_PARAM_SHADOW_SPLIT_2_OFFSET" value="10" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_SPLIT_2_OFFSET" value="11" enum="LightParam"> Proportion of shadow atlas occupied by the second split. </constant> - <constant name="LIGHT_PARAM_SHADOW_SPLIT_3_OFFSET" value="11" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_SPLIT_3_OFFSET" value="12" enum="LightParam"> Proportion of shadow atlas occupied by the third split. The fourth split occupies the rest. </constant> - <constant name="LIGHT_PARAM_SHADOW_FADE_START" value="12" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_FADE_START" value="13" enum="LightParam"> Proportion of shadow max distance where the shadow will start to fade out. </constant> - <constant name="LIGHT_PARAM_SHADOW_NORMAL_BIAS" value="13" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_NORMAL_BIAS" value="14" enum="LightParam"> Normal bias used to offset shadow lookup by object normal. Can be used to fix self-shadowing artifacts. </constant> - <constant name="LIGHT_PARAM_SHADOW_BIAS" value="14" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_BIAS" value="15" enum="LightParam"> Bias the shadow lookup to fix self-shadowing artifacts. </constant> - <constant name="LIGHT_PARAM_SHADOW_PANCAKE_SIZE" value="15" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_PANCAKE_SIZE" value="16" enum="LightParam"> Sets the size of the directional shadow pancake. The pancake offsets the start of the shadow's camera frustum to provide a higher effective depth resolution for the shadow. However, a high pancake size can cause artifacts in the shadows of large objects that are close to the edge of the frustum. Reducing the pancake size can help. Setting the size to [code]0[/code] turns off the pancaking effect. </constant> - <constant name="LIGHT_PARAM_SHADOW_OPACITY" value="16" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_OPACITY" value="17" enum="LightParam"> The light's shadow opacity. Values lower than [code]1.0[/code] make the light appear through shadows. This can be used to fake global illumination at a low performance cost. </constant> - <constant name="LIGHT_PARAM_SHADOW_BLUR" value="17" enum="LightParam"> + <constant name="LIGHT_PARAM_SHADOW_BLUR" value="18" enum="LightParam"> Blurs the edges of the shadow. Can be used to hide pixel artifacts in low resolution shadow maps. A high value can make shadows appear grainy and can cause other unwanted artifacts. Try to keep as near default as possible. </constant> - <constant name="LIGHT_PARAM_SHADOW_VOLUMETRIC_FOG_FADE" value="18" enum="LightParam"> - </constant> <constant name="LIGHT_PARAM_TRANSMITTANCE_BIAS" value="19" enum="LightParam"> </constant> <constant name="LIGHT_PARAM_MAX" value="20" enum="LightParam"> diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index 45ca330b87..5a0766263a 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -71,7 +71,7 @@ Force updates the bone transform for the bone at [param bone_idx] and all of its children. </description> </method> - <method name="get_bone_children"> + <method name="get_bone_children" qualifiers="const"> <return type="PackedInt32Array" /> <param index="0" name="bone_idx" type="int" /> <description> @@ -172,7 +172,7 @@ Returns the modification stack attached to this skeleton, if one exists. </description> </method> - <method name="get_parentless_bones"> + <method name="get_parentless_bones" qualifiers="const"> <return type="PackedInt32Array" /> <description> Returns an array with all of the bones that are parentless. Another way to look at this is that it returns the indexes of all the bones that are not dependent or modified by other bones in the Skeleton. diff --git a/doc/classes/String.xml b/doc/classes/String.xml index f1cd4d72f7..316bb923b7 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -566,11 +566,11 @@ Formats a number to have an exact number of [param digits] before the decimal point. </description> </method> - <method name="plus_file" qualifiers="const"> + <method name="path_join" qualifiers="const"> <return type="String" /> <param index="0" name="file" type="String" /> <description> - If the string is a path, this concatenates [param file] at the end of the string as a subpath. E.g. [code]"this/is".plus_file("path") == "this/is/path"[/code]. + If the string is a path, this concatenates [param file] at the end of the string as a subpath. E.g. [code]"this/is".path_join("path") == "this/is/path"[/code]. </description> </method> <method name="repeat" qualifiers="const"> @@ -775,6 +775,12 @@ Converts the String (which is a character array) to ASCII/Latin-1 encoded [PackedByteArray] (which is an array of bytes). The conversion is faster compared to [method to_utf8_buffer], as this method assumes that all the characters in the String are ASCII/Latin-1 characters, unsupported characters are replaced with spaces. </description> </method> + <method name="to_camel_case" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to [code]camelCase[/code]. + </description> + </method> <method name="to_float" qualifiers="const"> <return type="float" /> <description> @@ -804,6 +810,18 @@ Returns the string converted to lowercase. </description> </method> + <method name="to_pascal_case" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to [code]PascalCase[/code]. + </description> + </method> + <method name="to_snake_case" qualifiers="const"> + <return type="String" /> + <description> + Returns the string converted to [code]snake_case[/code]. + </description> + </method> <method name="to_upper" qualifiers="const"> <return type="String" /> <description> diff --git a/doc/classes/TabContainer.xml b/doc/classes/TabContainer.xml index 74f258072c..302f9b329b 100644 --- a/doc/classes/TabContainer.xml +++ b/doc/classes/TabContainer.xml @@ -258,5 +258,8 @@ <theme_item name="tab_unselected" data_type="style" type="StyleBox"> The style of the other, unselected tabs. </theme_item> + <theme_item name="tabbar_background" data_type="style" type="StyleBox"> + The style for the background fill of the [TabBar] area. + </theme_item> </theme_items> </class> diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index 14aa72b80c..18b4f9e6f9 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -141,14 +141,6 @@ This can be seen as transforming with respect to the local frame. </description> </method> - <method name="spherical_interpolate_with" qualifiers="const"> - <return type="Transform3D" /> - <param index="0" name="xform" type="Transform3D" /> - <param index="1" name="weight" type="float" /> - <description> - Returns a transform spherically interpolated between this transform and another by a given [param weight] (on the range of 0.0 to 1.0). - </description> - </method> <method name="translated" qualifiers="const"> <return type="Transform3D" /> <param index="0" name="offset" type="Vector3" /> diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml index 6d4408cf61..fdae6d205d 100644 --- a/doc/classes/TreeItem.xml +++ b/doc/classes/TreeItem.xml @@ -16,9 +16,9 @@ <param index="1" name="button" type="Texture2D" /> <param index="2" name="id" type="int" default="-1" /> <param index="3" name="disabled" type="bool" default="false" /> - <param index="4" name="tooltip" type="String" default="""" /> + <param index="4" name="tooltip_text" type="String" default="""" /> <description> - Adds a button with [Texture2D] [param button] at column [param column]. The [param id] is used to identify the button. If not specified, the next available index is used, which may be retrieved by calling [method get_button_count] immediately before this method. Optionally, the button can be [param disabled] and have a [param tooltip]. + Adds a button with [Texture2D] [param button] at column [param column]. The [param id] is used to identify the button. If not specified, the next available index is used, which may be retrieved by calling [method get_button_count] immediately before this method. Optionally, the button can be [param disabled] and have a [param tooltip_text]. </description> </method> <method name="call_recursive" qualifiers="vararg"> @@ -96,12 +96,12 @@ Returns the id for the button at index [param button_idx] in column [param column]. </description> </method> - <method name="get_button_tooltip" qualifiers="const"> + <method name="get_button_tooltip_text" qualifiers="const"> <return type="String" /> <param index="0" name="column" type="int" /> <param index="1" name="button_idx" type="int" /> <description> - Returns the tooltip string for the button at index [param button_idx] in column [param column]. + Returns the tooltip text for the button at index [param button_idx] in column [param column]. </description> </method> <method name="get_cell_mode" qualifiers="const"> @@ -308,11 +308,11 @@ Returns item's text base writing direction. </description> </method> - <method name="get_tooltip" qualifiers="const"> + <method name="get_tooltip_text" qualifiers="const"> <return type="String" /> <param index="0" name="column" type="int" /> <description> - Returns the given column's tooltip. + Returns the given column's tooltip text. </description> </method> <method name="get_tree" qualifiers="const"> @@ -639,7 +639,7 @@ Sets item's text base writing direction. </description> </method> - <method name="set_tooltip"> + <method name="set_tooltip_text"> <return type="void" /> <param index="0" name="column" type="int" /> <param index="1" name="tooltip" type="String" /> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 0071834ccd..87ee26fa32 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -218,8 +218,11 @@ To control this property on the root viewport, set the [member ProjectSettings.rendering/mesh_lod/lod_change/threshold_pixels] project setting. [b]Note:[/b] [member mesh_lod_threshold] does not affect [GeometryInstance3D] visibility ranges (also known as "manual" LOD or hierarchical LOD). </member> - <member name="msaa" type="int" setter="set_msaa" getter="get_msaa" enum="Viewport.MSAA" default="0"> - The multisample anti-aliasing mode. A higher number results in smoother edges at the cost of significantly worse performance. A value of 2 or 4 is best unless targeting very high-end systems. See also bilinear scaling 3d [member scaling_3d_mode] for supersampling, which provides higher quality but is much more expensive. + <member name="msaa_2d" type="int" setter="set_msaa_2d" getter="get_msaa_2d" enum="Viewport.MSAA" default="0"> + The multisample anti-aliasing mode for 2D/Canvas rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of 2 or 4 is best unless targeting very high-end systems. This has no effect on shader-induced aliasing or texture aliasing. + </member> + <member name="msaa_3d" type="int" setter="set_msaa_3d" getter="get_msaa_3d" enum="Viewport.MSAA" default="0"> + The multisample anti-aliasing mode for 3D rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of 2 or 4 is best unless targeting very high-end systems. See also bilinear scaling 3d [member scaling_3d_mode] for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. </member> <member name="own_world_3d" type="bool" setter="set_use_own_world_3d" getter="is_using_own_world_3d" default="false"> If [code]true[/code], the viewport will use a unique copy of the [World3D] defined in [member world_3d]. @@ -250,7 +253,7 @@ To control this property on the root viewport, set the [member ProjectSettings.rendering/scaling_3d/mode] project setting. </member> <member name="scaling_3d_scale" type="float" setter="set_scaling_3d_scale" getter="get_scaling_3d_scale" default="1.0"> - Scales the 3D render buffer based on the viewport size uses an image filter specified in [member ProjectSettings.rendering/scaling_3d/mode] to scale the output image to the full viewport size. Values lower than [code]1.0[/code] can be used to speed up 3D rendering at the cost of quality (undersampling). Values greater than [code]1.0[/code] are only valid for bilinear mode and can be used to improve 3D rendering quality at a high performance cost (supersampling). See also [member ProjectSettings.rendering/anti_aliasing/quality/msaa] for multi-sample antialiasing, which is significantly cheaper but only smoothens the edges of polygons. + Scales the 3D render buffer based on the viewport size uses an image filter specified in [member ProjectSettings.rendering/scaling_3d/mode] to scale the output image to the full viewport size. Values lower than [code]1.0[/code] can be used to speed up 3D rendering at the cost of quality (undersampling). Values greater than [code]1.0[/code] are only valid for bilinear mode and can be used to improve 3D rendering quality at a high performance cost (supersampling). See also [member ProjectSettings.rendering/anti_aliasing/quality/msaa_3d] for multi-sample antialiasing, which is significantly cheaper but only smooths the edges of polygons. When using FSR upscaling, AMD recommends exposing the following values as preset options to users "Ultra Quality: 0.77", "Quality: 0.67", "Balanced: 0.59", "Performance: 0.5" instead of exposing the entire scale. To control this property on the root viewport, set the [member ProjectSettings.rendering/scaling_3d/scale] project setting. </member> diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index bc50e39812..cd7de085d8 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -19,7 +19,7 @@ import version # $DOCS_URL/path/to/page.html(#fragment-tag) GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$") -# Based on reStructedText inline markup recognition rules +# Based on reStructuredText inline markup recognition rules # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules MARKUP_ALLOWED_PRECEDENT = " -:/'\"<([{" MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>" @@ -98,7 +98,7 @@ class State: property_name = property.attrib["name"] if property_name in class_def.properties: - print_error('{}.xml: Duplicate property "{}".'.format(class_name, property_name), self) + print_error(f'{class_name}.xml: Duplicate property "{property_name}".', self) continue type_name = TypeName.from_element(property) @@ -106,7 +106,7 @@ class State: getter = property.get("getter") or None default_value = property.get("default") or None if default_value is not None: - default_value = "``{}``".format(default_value) + default_value = f"``{default_value}``" overrides = property.get("overrides") or None property_def = PropertyDef( @@ -211,7 +211,7 @@ class State: constant_def = ConstantDef(constant_name, value, constant.text, is_bitfield) if enum is None: if constant_name in class_def.constants: - print_error('{}.xml: Duplicate constant "{}".'.format(class_name, constant_name), self) + print_error(f'{class_name}.xml: Duplicate constant "{constant_name}".', self) continue class_def.constants[constant_name] = constant_def @@ -255,7 +255,7 @@ class State: signal_name = signal.attrib["name"] if signal_name in class_def.signals: - print_error('{}.xml: Duplicate signal "{}".'.format(class_name, signal_name), self) + print_error(f'{class_name}.xml: Duplicate signal "{signal_name}".', self) continue params = self.parse_params(signal, "signal") @@ -278,16 +278,14 @@ class State: theme_item_id = "{}_{}".format(theme_item_data_name, theme_item_name) if theme_item_id in class_def.theme_items: print_error( - '{}.xml: Duplicate theme item "{}" of type "{}".'.format( - class_name, theme_item_name, theme_item_data_name - ), + f'{class_name}.xml: Duplicate theme item "{theme_item_name}" of type "{theme_item_data_name}".', self, ) continue default_value = theme_item.get("default") or None if default_value is not None: - default_value = "``{}``".format(default_value) + default_value = f"``{default_value}``" theme_item_def = ThemeItemDef( theme_item_name, @@ -320,9 +318,7 @@ class State: if param_name.strip() == "" or param_name.startswith("_unnamed_arg"): print_error( - '{}.xml: Empty argument name in {} "{}" at position {}.'.format( - self.current_class, context, root.attrib["name"], param_index - ), + f'{self.current_class}.xml: Empty argument name in {context} "{root.attrib["name"]}" at position {param_index}.', self, ) @@ -540,7 +536,7 @@ def main() -> None: if entry.msgid in BASE_STRINGS: strings_l10n[entry.msgid] = entry.msgstr else: - print('No PO file at "{}" for language "{}".'.format(lang_file, args.lang)) + print(f'No PO file at "{lang_file}" for language "{args.lang}".') print("Checking for errors in the XML class reference...") @@ -563,7 +559,7 @@ def main() -> None: elif os.path.isfile(path): if not path.endswith(".xml"): - print('Got non-.xml file "{}" in input, skipping.'.format(path)) + print(f'Got non-.xml file "{path}" in input, skipping.') continue file_list.append(path) @@ -575,17 +571,17 @@ def main() -> None: try: tree = ET.parse(cur_file) except ET.ParseError as e: - print_error("{}: Parse error while reading the file: {}".format(cur_file, e), state) + print_error(f"{cur_file}: Parse error while reading the file: {e}", state) continue doc = tree.getroot() if "version" not in doc.attrib: - print_error('{}: "version" attribute missing from "doc".'.format(cur_file), state) + print_error(f'{cur_file}: "version" attribute missing from "doc".', state) continue name = doc.attrib["name"] if name in classes: - print_error('{}: Duplicate class "{}".'.format(cur_file, name), state) + print_error(f'{cur_file}: Duplicate class "{name}".', state) continue classes[name] = (doc, cur_file) @@ -594,7 +590,7 @@ def main() -> None: try: state.parse_class(data[0], data[1]) except Exception as e: - print_error("{}.xml: Exception while parsing class: {}".format(name, e), state) + print_error(f"{name}.xml: Exception while parsing class: {e}", state) state.sort_classes() @@ -615,33 +611,25 @@ def main() -> None: if state.num_warnings >= 2: print( - "{}{} warnings were found in the class reference XML. Please check the messages above.{}".format( - STYLES["yellow"], state.num_warnings, STYLES["reset"] - ) + f'{STYLES["yellow"]}{state.num_warnings} warnings were found in the class reference XML. Please check the messages above.{STYLES["reset"]}' ) elif state.num_warnings == 1: print( - "{}1 warning was found in the class reference XML. Please check the messages above.{}".format( - STYLES["yellow"], STYLES["reset"] - ) + f'{STYLES["yellow"]}1 warning was found in the class reference XML. Please check the messages above.{STYLES["reset"]}' ) if state.num_errors == 0: - print("{}No errors found in the class reference XML.{}".format(STYLES["green"], STYLES["reset"])) + print(f'{STYLES["green"]}No errors found in the class reference XML.{STYLES["reset"]}') if not args.dry_run: - print("Wrote reStructuredText files for each class to: %s" % args.output) + print(f"Wrote reStructuredText files for each class to: {args.output}") else: if state.num_errors >= 2: print( - "{}{} errors were found in the class reference XML. Please check the messages above.{}".format( - STYLES["red"], state.num_errors, STYLES["reset"] - ) + f'{STYLES["red"]}{state.num_errors} errors were found in the class reference XML. Please check the messages above.{STYLES["reset"]}' ) else: print( - "{}1 error was found in the class reference XML. Please check the messages above.{}".format( - STYLES["red"], STYLES["reset"] - ) + f'{STYLES["red"]}1 error was found in the class reference XML. Please check the messages above.{STYLES["reset"]}' ) exit(1) @@ -650,12 +638,12 @@ def main() -> None: def print_error(error: str, state: State) -> None: - print("{}{}ERROR:{} {}{}".format(STYLES["red"], STYLES["bold"], STYLES["regular"], error, STYLES["reset"])) + print(f'{STYLES["red"]}{STYLES["bold"]}ERROR:{STYLES["regular"]} {error}{STYLES["reset"]}') state.num_errors += 1 -def print_warning(error: str, state: State) -> None: - print("{}{}WARNING:{} {}{}".format(STYLES["yellow"], STYLES["bold"], STYLES["regular"], error, STYLES["reset"])) +def print_warning(warning: str, state: State) -> None: + print(f'{STYLES["yellow"]}{STYLES["bold"]}WARNING:{STYLES["regular"]} {warning}{STYLES["reset"]}') state.num_warnings += 1 @@ -676,7 +664,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if dry_run: f = open(os.devnull, "w", encoding="utf-8") else: - f = open(os.path.join(output_dir, "class_" + class_name.lower() + ".rst"), "w", encoding="utf-8") + f = open(os.path.join(output_dir, f"class_{class_name.lower()}.rst"), "w", encoding="utf-8") # Remove the "Edit on Github" button from the online docs page. f.write(":github_url: hide\n\n") @@ -689,23 +677,23 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: git_branch = version.docs source_xml_path = os.path.relpath(class_def.filepath, root_directory).replace("\\", "/") - source_github_url = "https://github.com/godotengine/godot/tree/{}/{}".format(git_branch, source_xml_path) - generator_github_url = "https://github.com/godotengine/godot/tree/{}/doc/tools/make_rst.py".format(git_branch) + source_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/{source_xml_path}" + generator_github_url = f"https://github.com/godotengine/godot/tree/{git_branch}/doc/tools/make_rst.py" f.write(".. DO NOT EDIT THIS FILE!!!\n") f.write(".. Generated automatically from Godot engine sources.\n") - f.write(".. Generator: " + generator_github_url + ".\n") - f.write(".. XML source: " + source_github_url + ".\n\n") + f.write(f".. Generator: {generator_github_url}.\n") + f.write(f".. XML source: {source_github_url}.\n\n") # Document reference id and header. - f.write(".. _class_" + class_name + ":\n\n") + f.write(f".. _class_{class_name}:\n\n") f.write(make_heading(class_name, "=", False)) # Inheritance tree # Ascendants if class_def.inherits: inherits = class_def.inherits.strip() - f.write("**" + translate("Inherits:") + "** ") + f.write(f'**{translate("Inherits:")}** ') first = True while inherits in state.classes: if not first: @@ -728,7 +716,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: inherited.append(c.name) if len(inherited): - f.write("**" + translate("Inherited By:") + "** ") + f.write(f'**{translate("Inherited By:")}** ') for i, child in enumerate(inherited): if i > 0: f.write(", ") @@ -737,18 +725,18 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Brief description if class_def.brief_description is not None: - f.write(format_text_block(class_def.brief_description.strip(), class_def, state) + "\n\n") + f.write(f"{format_text_block(class_def.brief_description.strip(), class_def, state)}\n\n") # Class description if class_def.description is not None and class_def.description.strip() != "": f.write(make_heading("Description", "-")) - f.write(format_text_block(class_def.description.strip(), class_def, state) + "\n\n") + f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n") # Online tutorials if len(class_def.tutorials) > 0: f.write(make_heading("Tutorials", "-")) for url, title in class_def.tutorials: - f.write("- " + make_link(url, title) + "\n\n") + f.write(f"- {make_link(url, title)}\n\n") # Properties overview if len(class_def.properties) > 0: @@ -758,11 +746,11 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: type_rst = property_def.type_name.to_rst(state) default = property_def.default_value if default is not None and property_def.overrides: - ref = ":ref:`{1}<class_{1}_property_{0}>`".format(property_def.name, property_def.overrides) + ref = f":ref:`{property_def.overrides}<class_{property_def.overrides}_property_{property_def.name}>`" # Not using translate() for now as it breaks table formatting. - ml.append((type_rst, property_def.name, default + " " + "(overrides %s)" % ref)) + ml.append((type_rst, property_def.name, f"{default} (overrides {ref})")) else: - ref = ":ref:`{0}<class_{1}_property_{0}>`".format(property_def.name, class_name) + ref = f":ref:`{property_def.name}<class_{class_name}_property_{property_def.name}>`" ml.append((type_rst, ref, default)) format_table(f, ml, True) @@ -796,9 +784,7 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(make_heading("Theme Properties", "-")) pl: List[Tuple[Optional[str], ...]] = [] for theme_item_def in class_def.theme_items.values(): - ref = ":ref:`{0}<class_{2}_theme_{1}_{0}>`".format( - theme_item_def.name, theme_item_def.data_name, class_name - ) + ref = f":ref:`{theme_item_def.name}<class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}>`" pl.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) format_table(f, pl, True) @@ -811,12 +797,12 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if index != 0: f.write("----\n\n") - f.write(".. _class_{}_signal_{}:\n\n".format(class_name, signal.name)) + f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") _, signature = make_method_signature(class_def, signal, "", state) - f.write("- {}\n\n".format(signature)) + f.write(f"- {signature}\n\n") if signal.description is not None and signal.description.strip() != "": - f.write(format_text_block(signal.description.strip(), signal, state) + "\n\n") + f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") index += 1 @@ -829,24 +815,24 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if index != 0: f.write("----\n\n") - f.write(".. _enum_{}_{}:\n\n".format(class_name, e.name)) + f.write(f".. _enum_{class_name}_{e.name}:\n\n") # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. # As to why I'm not modifying the reference parser to directly link to the _enum label: # If somebody gets annoyed enough to fix it, all existing references will magically improve. for value in e.values.values(): - f.write(".. _class_{}_constant_{}:\n\n".format(class_name, value.name)) + f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") if e.is_bitfield: - f.write("flags **{}**:\n\n".format(e.name)) + f.write(f"flags **{e.name}**:\n\n") else: - f.write("enum **{}**:\n\n".format(e.name)) + f.write(f"enum **{e.name}**:\n\n") for value in e.values.values(): - f.write("- **{}** = **{}**".format(value.name, value.value)) + f.write(f"- **{value.name}** = **{value.value}**") if value.text is not None and value.text.strip() != "": # If value.text contains a bullet point list, each entry needs additional indentation - f.write(" --- " + indent_bullets(format_text_block(value.text.strip(), value, state))) + f.write(f" --- {indent_bullets(format_text_block(value.text.strip(), value, state))}") f.write("\n\n") @@ -858,12 +844,12 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. for constant in class_def.constants.values(): - f.write(".. _class_{}_constant_{}:\n\n".format(class_name, constant.name)) + f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") for constant in class_def.constants.values(): - f.write("- **{}** = **{}**".format(constant.name, constant.value)) + f.write(f"- **{constant.name}** = **{constant.value}**") if constant.text is not None and constant.text.strip() != "": - f.write(" --- " + format_text_block(constant.text.strip(), constant, state)) + f.write(f" --- {format_text_block(constant.text.strip(), constant, state)}") f.write("\n\n") @@ -878,13 +864,13 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write("----\n\n") if i == 0: - f.write(".. _class_{}_annotation_{}:\n\n".format(class_name, m.name)) + f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n") _, signature = make_method_signature(class_def, m, "", state) - f.write("- {}\n\n".format(signature)) + f.write(f"- {signature}\n\n") if m.description is not None and m.description.strip() != "": - f.write(format_text_block(m.description.strip(), m, state) + "\n\n") + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") index += 1 @@ -900,23 +886,23 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if index != 0: f.write("----\n\n") - f.write(".. _class_{}_property_{}:\n\n".format(class_name, property_def.name)) - f.write("- {} **{}**\n\n".format(property_def.type_name.to_rst(state), property_def.name)) + f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") + f.write(f"- {property_def.type_name.to_rst(state)} **{property_def.name}**\n\n") info: List[Tuple[Optional[str], ...]] = [] # Not using translate() for now as it breaks table formatting. if property_def.default_value is not None: - info.append(("*" + "Default" + "*", property_def.default_value)) + info.append(("*Default*", property_def.default_value)) if property_def.setter is not None and not property_def.setter.startswith("_"): - info.append(("*" + "Setter" + "*", property_def.setter + "(" + "value" + ")")) + info.append(("*Setter*", f"{property_def.setter}(value)")) if property_def.getter is not None and not property_def.getter.startswith("_"): - info.append(("*" + "Getter" + "*", property_def.getter + "()")) + info.append(("*Getter*", f"{property_def.getter}()")) if len(info) > 0: format_table(f, info) if property_def.text is not None and property_def.text.strip() != "": - f.write(format_text_block(property_def.text.strip(), property_def, state) + "\n\n") + f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n") index += 1 @@ -931,13 +917,13 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write("----\n\n") if i == 0: - f.write(".. _class_{}_constructor_{}:\n\n".format(class_name, m.name)) + f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n") ret_type, signature = make_method_signature(class_def, m, "", state) - f.write("- {} {}\n\n".format(ret_type, signature)) + f.write(f"- {ret_type} {signature}\n\n") if m.description is not None and m.description.strip() != "": - f.write(format_text_block(m.description.strip(), m, state) + "\n\n") + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") index += 1 @@ -951,13 +937,13 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write("----\n\n") if i == 0: - f.write(".. _class_{}_method_{}:\n\n".format(class_name, m.name)) + f.write(f".. _class_{class_name}_method_{m.name}:\n\n") ret_type, signature = make_method_signature(class_def, m, "", state) - f.write("- {} {}\n\n".format(ret_type, signature)) + f.write(f"- {ret_type} {signature}\n\n") if m.description is not None and m.description.strip() != "": - f.write(format_text_block(m.description.strip(), m, state) + "\n\n") + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") index += 1 @@ -972,16 +958,14 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if i == 0: f.write( - ".. _class_{}_operator_{}_{}:\n\n".format( - class_name, sanitize_operator_name(m.name, state), m.return_type.type_name - ) + f".. _class_{class_name}_operator_{sanitize_operator_name(m.name, state)}_{m.return_type.type_name}:\n\n" ) ret_type, signature = make_method_signature(class_def, m, "", state) - f.write("- {} {}\n\n".format(ret_type, signature)) + f.write(f"- {ret_type} {signature}\n\n") if m.description is not None and m.description.strip() != "": - f.write(format_text_block(m.description.strip(), m, state) + "\n\n") + f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") index += 1 @@ -994,19 +978,19 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if index != 0: f.write("----\n\n") - f.write(".. _class_{}_theme_{}_{}:\n\n".format(class_name, theme_item_def.data_name, theme_item_def.name)) - f.write("- {} **{}**\n\n".format(theme_item_def.type_name.to_rst(state), theme_item_def.name)) + f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n") + f.write(f"- {theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**\n\n") info = [] if theme_item_def.default_value is not None: # Not using translate() for now as it breaks table formatting. - info.append(("*" + "Default" + "*", theme_item_def.default_value)) + info.append(("*Default*", theme_item_def.default_value)) if len(info) > 0: format_table(f, info) if theme_item_def.text is not None and theme_item_def.text.strip() != "": - f.write(format_text_block(theme_item_def.text.strip(), theme_item_def, state) + "\n\n") + f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n") index += 1 @@ -1020,8 +1004,8 @@ def make_type(klass: str, state: State) -> str: if link_type.endswith("[]"): # Typed array, strip [] to link to contained type. link_type = link_type[:-2] if link_type in state.classes: - return ":ref:`{}<class_{}>`".format(klass, link_type) - print_error('{}.xml: Unresolved type "{}".'.format(state.current_class, klass), state) + return f":ref:`{klass}<class_{link_type}>`" + print_error(f'{state.current_class}.xml: Unresolved type "{klass}".', state) return klass @@ -1041,11 +1025,11 @@ def make_enum(t: str, state: State) -> str: c = "@GlobalScope" if c in state.classes and e in state.classes[c].enums: - return ":ref:`{0}<enum_{1}_{0}>`".format(e, c) + return f":ref:`{e}<enum_{c}_{e}>`" # Don't fail for `Vector3.Axis`, as this enum is a special case which is expected not to be resolved. - if "{}.{}".format(c, e) != "Vector3.Axis": - print_error('{}.xml: Unresolved enum "{}".'.format(state.current_class, t), state) + if f"{c}.{e}" != "Vector3.Axis": + print_error(f'{state.current_class}.xml: Unresolved enum "{t}".', state) return t @@ -1067,17 +1051,12 @@ def make_method_signature( if is_method_def and ref_type != "": if ref_type == "operator": - out += ":ref:`{0}<class_{1}_{2}_{3}_{4}>` ".format( - definition.name.replace("<", "\\<"), # So operator "<" gets correctly displayed. - class_def.name, - ref_type, - sanitize_operator_name(definition.name, state), - definition.return_type.type_name, - ) + op_name = definition.name.replace("<", "\\<") # So operator "<" gets correctly displayed. + out += f":ref:`{op_name}<class_{class_def.name}_{ref_type}_{sanitize_operator_name(definition.name, state)}_{definition.return_type.type_name}>` " else: - out += ":ref:`{0}<class_{1}_{2}_{0}>` ".format(definition.name, class_def.name, ref_type) + out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>` " else: - out += "**{}** ".format(definition.name) + out += f"**{definition.name}** " out += "**(**" for i, arg in enumerate(definition.parameters): @@ -1086,10 +1065,10 @@ def make_method_signature( else: out += " " - out += "{} {}".format(arg.type_name.to_rst(state), arg.name) + out += f"{arg.type_name.to_rst(state)} {arg.name}" if arg.default_value is not None: - out += "=" + arg.default_value + out += f"={arg.default_value}" if qualifiers is not None and "vararg" in qualifiers: if len(definition.parameters) > 0: @@ -1103,7 +1082,7 @@ def make_method_signature( # Use substitutions for abbreviations. This is used to display tooltips on hover. # See `make_footer()` for descriptions. for qualifier in qualifiers.split(): - out += " |" + qualifier + "|" + out += f" |{qualifier}|" return ret_type, out @@ -1114,22 +1093,29 @@ def make_heading(title: str, underline: str, l10n: bool = True) -> str: if new_title != title: title = new_title underline *= 2 # Double length to handle wide chars. - return title + "\n" + (underline * len(title)) + "\n\n" + return f"{title}\n{(underline * len(title))}\n\n" def make_footer() -> str: # Generate reusable abbreviation substitutions. # This way, we avoid bloating the generated rST with duplicate abbreviations. - # fmt: off + virtual_msg = translate("This method should typically be overridden by the user to have any effect.") + const_msg = translate("This method has no side effects. It doesn't modify any of the instance's member variables.") + vararg_msg = translate("This method accepts any number of arguments after the ones described here.") + constructor_msg = translate("This method is used to construct a type.") + static_msg = translate( + "This method doesn't need an instance to be called, so it can be called directly using the class name." + ) + operator_msg = translate("This method describes a valid operator to use with this type as left-hand operand.") + return ( - ".. |virtual| replace:: :abbr:`virtual (" + translate("This method should typically be overridden by the user to have any effect.") + ")`\n" - ".. |const| replace:: :abbr:`const (" + translate("This method has no side effects. It doesn't modify any of the instance's member variables.") + ")`\n" - ".. |vararg| replace:: :abbr:`vararg (" + translate("This method accepts any number of arguments after the ones described here.") + ")`\n" - ".. |constructor| replace:: :abbr:`constructor (" + translate("This method is used to construct a type.") + ")`\n" - ".. |static| replace:: :abbr:`static (" + translate("This method doesn't need an instance to be called, so it can be called directly using the class name.") + ")`\n" - ".. |operator| replace:: :abbr:`operator (" + translate("This method describes a valid operator to use with this type as left-hand operand.") + ")`\n" + f".. |virtual| replace:: :abbr:`virtual ({virtual_msg})`\n" + f".. |const| replace:: :abbr:`const ({const_msg})`\n" + f".. |vararg| replace:: :abbr:`vararg ({vararg_msg})`\n" + f".. |constructor| replace:: :abbr:`constructor ({constructor_msg})`\n" + f".. |static| replace:: :abbr:`static ({static_msg})`\n" + f".. |operator| replace:: :abbr:`operator ({operator_msg})`\n" ) - # fmt: on def make_link(url: str, title: str) -> str: @@ -1141,20 +1127,20 @@ def make_link(url: str, title: str) -> str: # `#calling-javascript-from-script in Exporting For Web` # Or use the title if provided. if title != "": - return "`" + title + " <../" + groups[0] + ".html" + groups[1] + ">`__" - return "`" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`__ in :doc:`../" + groups[0] + "`" + return f"`{title} <../{groups[0]}.html{groups[1]}>`__" + return f"`{groups[1]} <../{groups[0]}.html{groups[1]}>`__ in :doc:`../{groups[0]}`" elif match.lastindex == 1: # Doc reference, for example: # `Math` if title != "": - return ":doc:`" + title + " <../" + groups[0] + ">`" - return ":doc:`../" + groups[0] + "`" + return f":doc:`{title} <../{groups[0]}>`" + return f":doc:`../{groups[0]}`" # External link, for example: # `http://enet.bespin.org/usergroup0.html` if title != "": - return "`" + title + " <" + url + ">`__" - return "`" + url + " <" + url + ">`__" + return f"`{title} <{url}>`__" + return f"`{url} <{url}>`__" # Formatting helpers. @@ -1209,12 +1195,12 @@ def format_text_block( result = format_codeblock(block_type, post_text, indent_level, state) if result is None: return "" - text = pre_text + result[0] + text = f"{pre_text}{result[0]}" pos += result[1] - indent_level # Handle normal text else: - text = pre_text + "\n\n" + post_text + text = f"{pre_text}\n\n{post_text}" pos += 2 - indent_level next_brac_pos = text.find("[") @@ -1248,13 +1234,13 @@ def format_text_block( if tag_text in state.classes: if tag_text == state.current_class: # Don't create a link to the same class, format it as inline code. - tag_text = "``{}``".format(tag_text) + tag_text = f"``{tag_text}``" else: tag_text = make_type(tag_text, state) escape_pre = True escape_post = True - # Tag is a cross-reference or a formating directive. + # Tag is a cross-reference or a formatting directive. else: cmd = tag_text space_pos = tag_text.find(" ") @@ -1282,13 +1268,11 @@ def format_text_block( else: if cmd.startswith("/"): print_warning( - '{}.xml: Potential error inside of a code tag, found a string that looks like a closing tag "[{}]" in {}.'.format( - state.current_class, cmd, context_name - ), + f'{state.current_class}.xml: Potential error inside of a code tag, found a string that looks like a closing tag "[{cmd}]" in {context_name}.', state, ) - tag_text = "[" + tag_text + "]" + tag_text = f"[{tag_text}]" # Entering codeblocks and inline code tags. @@ -1307,18 +1291,14 @@ def format_text_block( if cmd == "gdscript": if not inside_code_tabs: print_error( - "{}.xml: GDScript code block is used outside of [codeblocks] in {}.".format( - state.current_class, cmd, context_name - ), + f"{state.current_class}.xml: GDScript code block is used outside of [codeblocks] in {context_name}.", state, ) tag_text = "\n .. code-tab:: gdscript\n" elif cmd == "csharp": if not inside_code_tabs: print_error( - "{}.xml: C# code block is used outside of [codeblocks] in {}.".format( - state.current_class, cmd, context_name - ), + f"{state.current_class}.xml: C# code block is used outside of [codeblocks] in {context_name}.", state, ) tag_text = "\n .. code-tab:: csharp\n" @@ -1345,7 +1325,7 @@ def format_text_block( if link_target == "": print_error( - '{}.xml: Empty cross-reference link "{}" in {}.'.format(state.current_class, cmd, context_name), + f'{state.current_class}.xml: Empty cross-reference link "{cmd}" in {context_name}.', state, ) tag_text = "" @@ -1364,9 +1344,7 @@ def format_text_block( ss = link_target.split(".") if len(ss) > 2: print_error( - '{}.xml: Bad reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Bad reference "{link_target}" in {context_name}.', state, ) class_param, method_param = ss @@ -1386,63 +1364,50 @@ def format_text_block( if cmd.startswith("method") and method_param not in class_def.methods: print_error( - '{}.xml: Unresolved method reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved method reference "{link_target}" in {context_name}.', state, ) elif cmd.startswith("constructor") and method_param not in class_def.constructors: print_error( - '{}.xml: Unresolved constructor reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved constructor reference "{link_target}" in {context_name}.', state, ) elif cmd.startswith("operator") and method_param not in class_def.operators: print_error( - '{}.xml: Unresolved operator reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved operator reference "{link_target}" in {context_name}.', state, ) elif cmd.startswith("member") and method_param not in class_def.properties: print_error( - '{}.xml: Unresolved member reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved member reference "{link_target}" in {context_name}.', state, ) elif cmd.startswith("signal") and method_param not in class_def.signals: print_error( - '{}.xml: Unresolved signal reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved signal reference "{link_target}" in {context_name}.', state, ) elif cmd.startswith("annotation") and method_param not in class_def.annotations: print_error( - '{}.xml: Unresolved annotation reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved annotation reference "{link_target}" in {context_name}.', state, ) elif cmd.startswith("theme_item"): if method_param not in class_def.theme_items: print_error( - '{}.xml: Unresolved theme item reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved theme item reference "{link_target}" in {context_name}.', state, ) else: # Needs theme data type to be properly linked, which we cannot get without a class. - ref_type = "_theme_{}".format(class_def.theme_items[method_param].data_name) + name = class_def.theme_items[method_param].data_name + ref_type = f"_theme_{name}" elif cmd.startswith("constant"): found = False @@ -1468,24 +1433,20 @@ def format_text_block( if not found: print_error( - '{}.xml: Unresolved constant reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved constant reference "{link_target}" in {context_name}.', state, ) else: print_error( - '{}.xml: Unresolved type reference "{}" in method reference "{}" in {}.'.format( - state.current_class, class_param, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved type reference "{class_param}" in method reference "{link_target}" in {context_name}.', state, ) repl_text = method_param if class_param != state.current_class: - repl_text = "{}.{}".format(class_param, method_param) - tag_text = ":ref:`{}<class_{}{}_{}>`".format(repl_text, class_param, ref_type, method_param) + repl_text = f"{class_param}.{method_param}" + tag_text = f":ref:`{repl_text}<class_{class_param}{ref_type}_{method_param}>`" escape_pre = True escape_post = True @@ -1502,9 +1463,7 @@ def format_text_block( ) if not valid_context: print_error( - '{}.xml: Argument reference "{}" used outside of method, signal, or annotation context in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Argument reference "{link_target}" used outside of method, signal, or annotation context in {context_name}.', state, ) else: @@ -1516,13 +1475,11 @@ def format_text_block( break if not found: print_error( - '{}.xml: Unresolved argument reference "{}" in {}.'.format( - state.current_class, link_target, context_name - ), + f'{state.current_class}.xml: Unresolved argument reference "{link_target}" in {context_name}.', state, ) - tag_text = "``{}``".format(link_target) + tag_text = f"``{link_target}``" # Formatting directives. @@ -1534,9 +1491,7 @@ def format_text_block( endurl_pos = text.find("[/url]", endq_pos + 1) if endurl_pos == -1: print_error( - "{}.xml: Tag depth mismatch for [url]: no closing [/url] in {}.".format( - state.current_class, context_name - ), + f"{state.current_class}.xml: Tag depth mismatch for [url]: no closing [/url] in {context_name}.", state, ) break @@ -1556,7 +1511,7 @@ def format_text_block( continue else: print_error( - '{}.xml: Misformatted [url] tag "{}" in {}.'.format(state.current_class, cmd, context_name), + f'{state.current_class}.xml: Misformatted [url] tag "{cmd}" in {context_name}.', state, ) @@ -1613,18 +1568,14 @@ def format_text_block( # Invalid syntax checks. elif cmd.startswith("/"): - print_error( - '{}.xml: Unrecognized closing tag "{}" in {}.'.format(state.current_class, cmd, context_name), state - ) + print_error(f'{state.current_class}.xml: Unrecognized closing tag "{cmd}" in {context_name}.', state) - tag_text = "[" + tag_text + "]" + tag_text = f"[{tag_text}]" else: - print_error( - '{}.xml: Unrecognized opening tag "{}" in {}.'.format(state.current_class, cmd, context_name), state - ) + print_error(f'{state.current_class}.xml: Unrecognized opening tag "{cmd}" in {context_name}.', state) - tag_text = "``{}``".format(tag_text) + tag_text = f"``{tag_text}``" escape_pre = True escape_post = True @@ -1640,7 +1591,7 @@ def format_text_block( iter_pos = post_text.find("*", iter_pos, next_brac_pos) if iter_pos == -1: break - post_text = post_text[:iter_pos] + "\*" + post_text[iter_pos + 1 :] + post_text = f"{post_text[:iter_pos]}\*{post_text[iter_pos + 1 :]}" iter_pos += 2 iter_pos = 0 @@ -1649,7 +1600,7 @@ def format_text_block( if iter_pos == -1: break if not post_text[iter_pos + 1].isalnum(): # don't escape within a snake_case word - post_text = post_text[:iter_pos] + "\_" + post_text[iter_pos + 1 :] + post_text = f"{post_text[:iter_pos]}\_{post_text[iter_pos + 1 :]}" iter_pos += 2 else: iter_pos += 1 @@ -1659,9 +1610,7 @@ def format_text_block( if tag_depth > 0: print_error( - "{}.xml: Tag depth mismatch: too many (or too little) open/close tags in {}.".format( - state.current_class, context_name - ), + f"{state.current_class}.xml: Tag depth mismatch: too many (or too few) open/close tags in {context_name}.", state, ) @@ -1671,7 +1620,7 @@ def format_text_block( def format_context_name(context: Union[DefinitionBase, None]) -> str: context_name: str = "unknown context" if context is not None: - context_name = '{} "{}" description'.format(context.definition_name, context.name) + context_name = f'{context.definition_name} "{context.name}" description' return context_name @@ -1683,7 +1632,7 @@ def escape_rst(text: str, until_pos: int = -1) -> str: pos = text.find("\\", pos, until_pos) if pos == -1: break - text = text[:pos] + "\\\\" + text[pos + 1 :] + text = f"{text[:pos]}\\\\{text[pos + 1 :]}" pos += 2 # Escape * character to avoid interpreting it as emphasis @@ -1692,7 +1641,7 @@ def escape_rst(text: str, until_pos: int = -1) -> str: pos = text.find("*", pos, until_pos) if pos == -1: break - text = text[:pos] + "\*" + text[pos + 1 :] + text = f"{text[:pos]}\*{text[pos + 1 :]}" pos += 2 # Escape _ character at the end of a word to avoid interpreting it as an inline hyperlink @@ -1702,7 +1651,7 @@ def escape_rst(text: str, until_pos: int = -1) -> str: if pos == -1: break if not text[pos + 1].isalnum(): # don't escape within a snake_case word - text = text[:pos] + "\_" + text[pos + 1 :] + text = f"{text[:pos]}\_{text[pos + 1 :]}" pos += 2 else: pos += 1 @@ -1713,10 +1662,10 @@ def escape_rst(text: str, until_pos: int = -1) -> str: def format_codeblock(code_type: str, post_text: str, indent_level: int, state: State) -> Union[Tuple[str, int], None]: end_pos = post_text.find("[/" + code_type + "]") if end_pos == -1: - print_error("{}.xml: [" + code_type + "] without a closing tag.".format(state.current_class), state) + print_error(f"{state.current_class}.xml: [{code_type}] without a closing tag.", state) return None - code_text = post_text[len("[" + code_type + "]") : end_pos] + code_text = post_text[len(f"[{code_type}]") : end_pos] post_text = post_text[end_pos:] # Remove extraneous tabs @@ -1732,19 +1681,17 @@ def format_codeblock(code_type: str, post_text: str, indent_level: int, state: S if to_skip > indent_level: print_error( - "{}.xml: Four spaces should be used for indentation within [{}].".format( - state.current_class, code_type - ), + f"{state.current_class}.xml: Four spaces should be used for indentation within [{code_type}].", state, ) if len(code_text[code_pos + to_skip + 1 :]) == 0: - code_text = code_text[:code_pos] + "\n" + code_text = f"{code_text[:code_pos]}\n" code_pos += 1 else: - code_text = code_text[:code_pos] + "\n " + code_text[code_pos + to_skip + 1 :] + code_text = f"{code_text[:code_pos]}\n {code_text[code_pos + to_skip + 1 :]}" code_pos += 5 - to_skip - return ("\n[" + code_type + "]" + code_text + post_text, len("\n[" + code_type + "]" + code_text)) + return (f"\n[{code_type}]{code_text}{post_text}", len(f"\n[{code_type}]{code_text}")) def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_columns: bool = False) -> None: @@ -1771,7 +1718,7 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ for i, text in enumerate(row): if column_sizes[i] == 0 and remove_empty_columns: continue - row_text += " " + (text or "").ljust(column_sizes[i]) + " |" + row_text += f' {(text or "").ljust(column_sizes[i])} |' row_text += "\n" f.write(row_text) f.write(sep) @@ -1831,7 +1778,7 @@ def sanitize_operator_name(dirty_name: str, state: State) -> str: else: clear_name = "xxx" - print_error('Unsupported operator type "{}", please add the missing rule.'.format(dirty_name), state) + print_error(f'Unsupported operator type "{dirty_name}", please add the missing rule.', state) return clear_name @@ -1850,7 +1797,7 @@ def indent_bullets(text: str) -> str: pos += 1 if pos < len(line) and line[pos] in bullet_points: - lines[line_index] = line[:pos] + "\t" + line[pos:] + lines[line_index] = f"{line[:pos]}\t{line[pos:]}" return "".join(lines) |