diff options
Diffstat (limited to 'doc')
34 files changed, 194 insertions, 72 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 9a28a0d085..7f7df33471 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -898,7 +898,7 @@ <constant name="KEY_MASK_CTRL" value="268435456" enum="KeyModifierMask"> Ctrl key mask. </constant> - <constant name="KEY_MASK_CMD" value="268435456" enum="KeyModifierMask"> + <constant name="KEY_MASK_CMD" value="platform-dependent" enum="KeyModifierMask"> Command key mask. On macOS, this is equivalent to [constant KEY_MASK_META]. On other platforms, this is equivalent to [constant KEY_MASK_CTRL]. This mask should be preferred to [constant KEY_MASK_META] or [constant KEY_MASK_CTRL] for system shortcuts as it handles all platforms correctly. </constant> <constant name="KEY_MASK_KPAD" value="536870912" enum="KeyModifierMask"> diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index 09811d5617..68f0a630ef 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -7,10 +7,10 @@ An Animation resource contains data used to animate everything in the engine. Animations are divided into tracks, and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track. [codeblock] # This creates an animation that makes the node "Enemy" move to the right by - # 100 pixels in 1 second. + # 100 pixels in 0.5 seconds. var animation = Animation.new() var track_index = animation.add_track(Animation.TYPE_VALUE) - animation.track_set_path(track_index, "Enemy:position.x") + animation.track_set_path(track_index, "Enemy:position:x") animation.track_insert_key(track_index, 0.0, 0) animation.track_insert_key(track_index, 0.5, 100) [/codeblock] diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index be361f93f3..899988022f 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -316,7 +316,16 @@ <argument index="4" name="clip_w" type="int" default="-1"> </argument> <description> - Draws a string using a custom font. + Draws [code]text[/code] using the specified [code]font[/code] at the [code]position[/code] (top-left corner). The text will have its color multiplied by [code]modulate[/code]. If [code]clip_w[/code] is greater than or equal to 0, the text will be clipped if it exceeds the specified width. + [b]Example using the default project font:[/b] + [codeblock] + # If using this method in a script that redraws constantly, move the + # `default_font` declaration to a member variable assigned in `_ready()` + # so the Control is only created once. + var default_font = Control.new().get_font("font") + draw_string(default_font, Vector2(64, 64), "Hello world") + [/codeblock] + See also [method Font.draw]. </description> </method> <method name="draw_style_box"> @@ -525,7 +534,7 @@ <return type="bool"> </return> <description> - Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and its inherited visibility is also [code]true[/code]. + Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree. </description> </method> <method name="make_canvas_position_local" qualifiers="const"> @@ -617,7 +626,8 @@ If [code]true[/code], the parent [CanvasItem]'s [member material] property is used as this one's material. </member> <member name="visible" type="bool" setter="set_visible" getter="is_visible" default="true"> - If [code]true[/code], this [CanvasItem] is drawn. For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead. + If [code]true[/code], this [CanvasItem] is drawn. The node is only visible if all of its antecedents are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]). + [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead. </member> </members> <signals> diff --git a/doc/classes/CollisionObject2D.xml b/doc/classes/CollisionObject2D.xml index bf82e921fb..e8f7a59e4c 100644 --- a/doc/classes/CollisionObject2D.xml +++ b/doc/classes/CollisionObject2D.xml @@ -217,7 +217,7 @@ </methods> <members> <member name="input_pickable" type="bool" setter="set_pickable" getter="is_pickable" default="true"> - If [code]true[/code], this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. + If [code]true[/code], this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. Requires at least one [code]collision_layer[/code] bit to be set. </member> </members> <signals> @@ -229,17 +229,17 @@ <argument index="2" name="shape_idx" type="int"> </argument> <description> - Emitted when an input event occurs and [code]input_pickable[/code] is [code]true[/code]. See [method _input_event] for details. + Emitted when an input event occurs. Requires [member input_pickable] to be [code]true[/code] and at least one [code]collision_layer[/code] bit to be set. See [method _input_event] for details. </description> </signal> <signal name="mouse_entered"> <description> - Emitted when the mouse pointer enters any of this object's shapes. + Emitted when the mouse pointer enters any of this object's shapes. Requires [member input_pickable] to be [code]true[/code] and at least one [code]collision_layer[/code] bit to be set. </description> </signal> <signal name="mouse_exited"> <description> - Emitted when the mouse pointer exits all this object's shapes. + Emitted when the mouse pointer exits all this object's shapes. Requires [member input_pickable] to be [code]true[/code] and at least one [code]collision_layer[/code] bit to be set. </description> </signal> </signals> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 49af8d7de2..814c232668 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -627,12 +627,14 @@ <return type="int"> </return> <description> + Returns the on-screen keyboard's height in pixels. Returns 0 if there is no keyboard or if it is currently hidden. </description> </method> <method name="virtual_keyboard_hide"> <return type="void"> </return> <description> + Hides the virtual keyboard if it is shown, does nothing otherwise. </description> </method> <method name="virtual_keyboard_show"> @@ -642,13 +644,23 @@ </argument> <argument index="1" name="position" type="Rect2" default="Rect2i( 0, 0, 0, 0 )"> </argument> - <argument index="2" name="max_length" type="int" default="-1"> + <argument index="2" name="multiline" type="bool" default="false"> </argument> - <argument index="3" name="cursor_start" type="int" default="-1"> + <argument index="3" name="max_length" type="int" default="-1"> </argument> - <argument index="4" name="cursor_end" type="int" default="-1"> + <argument index="4" name="cursor_start" type="int" default="-1"> + </argument> + <argument index="5" name="cursor_end" type="int" default="-1"> </argument> <description> + Shows the virtual keyboard if the platform has one. + [code]existing_text[/code] parameter is useful for implementing your own [LineEdit] or [TextEdit], as it tells the virtual keyboard what text has already been typed (the virtual keyboard uses it for auto-correct and predictions). + [code]position[/code] parameter is the screen space [Rect2] of the edited text. + [code]multiline[/code] parameter needs to be set to [code]true[/code] to be able to enter multiple lines of text, as in [TextEdit]. + [code]max_length[/code] limits the number of characters that can be entered if different from [code]-1[/code]. + [code]cursor_start[/code] can optionally define the current text cursor position if [code]cursor_end[/code] is not set. + [code]cursor_start[/code] and [code]cursor_end[/code] can optionally define the current text selection. + [b]Note:[/b] This method is implemented on Android, iOS and UWP. </description> </method> <method name="vsync_is_enabled" qualifiers="const"> diff --git a/doc/classes/EditorInspector.xml b/doc/classes/EditorInspector.xml index 5fbe427f67..6f03165a97 100644 --- a/doc/classes/EditorInspector.xml +++ b/doc/classes/EditorInspector.xml @@ -20,9 +20,7 @@ </method> </methods> <members> - <member name="scroll_horizontal_enabled" type="bool" setter="set_enable_h_scroll" getter="is_h_scroll_enabled" override="true" default="false"> - If [code]true[/code], horizontal scrolling is enabled. An horizontal scroll bar will display at the bottom of the inspector. - </member> + <member name="scroll_horizontal_enabled" type="bool" setter="set_enable_h_scroll" getter="is_h_scroll_enabled" override="true" default="false" /> </members> <signals> <signal name="object_id_selected"> diff --git a/doc/classes/EditorInterface.xml b/doc/classes/EditorInterface.xml index 8b2b9c9350..9da36b51f9 100644 --- a/doc/classes/EditorInterface.xml +++ b/doc/classes/EditorInterface.xml @@ -51,8 +51,8 @@ <return type="Control"> </return> <description> - Returns the editor's [Viewport] instance. - [b]Note:[/b] This returns the main editor viewport containing the whole editor, not the 2D or 3D viewports specifically. + Returns the main editor control. Use this as a parent for main screens. + [b]Note:[/b] This returns the main editor control containing the whole editor, not the 2D or 3D viewports specifically. </description> </method> <method name="get_file_system_dock"> diff --git a/doc/classes/EditorTranslationParserPlugin.xml b/doc/classes/EditorTranslationParserPlugin.xml index a40ef45916..d40fc558de 100644 --- a/doc/classes/EditorTranslationParserPlugin.xml +++ b/doc/classes/EditorTranslationParserPlugin.xml @@ -35,7 +35,7 @@ func get_recognized_extensions(): - return ["gd"] + return ["gd"] [/codeblock] </description> <tutorials> diff --git a/doc/classes/Font.xml b/doc/classes/Font.xml index 30b8c1fe76..ce6a25e191 100644 --- a/doc/classes/Font.xml +++ b/doc/classes/Font.xml @@ -26,6 +26,7 @@ </argument> <description> Draw [code]string[/code] into a canvas item using the font at a given position, with [code]modulate[/code] color, and optionally clipping the width. [code]position[/code] specifies the baseline, not the top. To draw from the top, [i]ascent[/i] must be added to the Y axis. + See also [method CanvasItem.draw_string]. </description> </method> <method name="draw_char" qualifiers="const"> diff --git a/doc/classes/InputEventMouseMotion.xml b/doc/classes/InputEventMouseMotion.xml index 53e6517c7a..c36089fe9b 100644 --- a/doc/classes/InputEventMouseMotion.xml +++ b/doc/classes/InputEventMouseMotion.xml @@ -5,6 +5,7 @@ </brief_description> <description> Contains mouse and pen motion information. Supports relative, absolute positions and speed. See [method Node._input]. + [b]Note:[/b] By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, call [method Input.set_use_accumulated_input] with [code]false[/code] to make events emitted as often as possible. If you use InputEventMouseMotion to draw lines, consider implementing [url=https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm]Bresenham's line algorithm[/url] as well to avoid visible gaps in lines if the user is moving the mouse quickly. </description> <tutorials> <link>https://docs.godotengine.org/en/latest/tutorials/inputs/mouse_and_input_coordinates.html</link> diff --git a/doc/classes/JSON.xml b/doc/classes/JSON.xml index 7bd2edcb1c..2e837dea1d 100644 --- a/doc/classes/JSON.xml +++ b/doc/classes/JSON.xml @@ -15,7 +15,7 @@ <argument index="0" name="json" type="String"> </argument> <description> - Parses a JSON encoded string and returns a [JSONParseResult] containing the result. + Parses a JSON-encoded string and returns a [JSONParseResult] containing the result. </description> </method> <method name="print"> @@ -29,6 +29,7 @@ </argument> <description> Converts a [Variant] var to JSON text and returns the result. Useful for serializing data to store or send over the network. + [b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, converting a Variant to JSON text will convert all numerical values to [float] types. </description> </method> </methods> diff --git a/doc/classes/JSONParseResult.xml b/doc/classes/JSONParseResult.xml index 4444e08593..4dbceb35e9 100644 --- a/doc/classes/JSONParseResult.xml +++ b/doc/classes/JSONParseResult.xml @@ -15,21 +15,21 @@ The error type if the JSON source was not successfully parsed. See the [enum Error] constants. </member> <member name="error_line" type="int" setter="set_error_line" getter="get_error_line" default="-1"> - The line number where the error occurred if JSON source was not successfully parsed. + The line number where the error occurred if the JSON source was not successfully parsed. </member> <member name="error_string" type="String" setter="set_error_string" getter="get_error_string" default=""""> - The error message if JSON source was not successfully parsed. See the [enum Error] constants. + The error message if the JSON source was not successfully parsed. See the [enum Error] constants. </member> <member name="result" type="Variant" setter="set_result" getter="get_result"> - A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with braces ([code][][/code]), an [Array] will be returned. - [b]Note:[/b] The JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to float types. + A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with brackets ([code][][/code]), an [Array] will be returned. + [b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, parsing a JSON text will convert all numerical values to [float] types. [b]Note:[/b] JSON objects do not preserve key order like Godot dictionaries, thus, you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements: [codeblock] var p = JSON.parse('["hello", "world", "!"]') if typeof(p.result) == TYPE_ARRAY: print(p.result[0]) # Prints "hello" else: - print("unexpected results") + push_error("Unexpected results.") [/codeblock] </member> </members> diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml index feac483fc4..f08a15d873 100644 --- a/doc/classes/LineEdit.xml +++ b/doc/classes/LineEdit.xml @@ -122,6 +122,8 @@ <member name="caret_blink_speed" type="float" setter="cursor_set_blink_speed" getter="cursor_get_blink_speed" default="0.65"> Duration (in seconds) of a caret's blinking cycle. </member> + <member name="caret_force_displayed" type="bool" setter="cursor_set_force_displayed" getter="cursor_get_force_displayed" default="false"> + </member> <member name="caret_position" type="int" setter="set_cursor_position" getter="get_cursor_position" default="0"> The cursor's position inside the [LineEdit]. When set, the text may scroll to accommodate it. </member> diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml index 05d00b9f31..02b319fb5a 100644 --- a/doc/classes/Node3D.xml +++ b/doc/classes/Node3D.xml @@ -101,7 +101,7 @@ <return type="bool"> </return> <description> - Returns whether the node is visible, taking into consideration that its parents visibility. + Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree. </description> </method> <method name="look_at"> @@ -323,7 +323,7 @@ Local translation of this node. </member> <member name="visible" type="bool" setter="set_visible" getter="is_visible" default="true"> - If [code]true[/code], this node is drawn. + If [code]true[/code], this node is drawn. The node is only visible if all of its antecedents are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]). </member> </members> <signals> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 5b4b5d02fb..26110df335 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -120,7 +120,7 @@ [codeblock] var arguments = {} for argument in OS.get_cmdline_args(): - if argument.find("=") > -1: + if argument.find("=") > -1: var key_value = argument.split("=") arguments[key_value[0].lstrip("--")] = key_value[1] [/codeblock] diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 3d8c2c5eb0..ca6b624359 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -17,8 +17,10 @@ [/codeblock] The [code]in[/code] operator will evaluate to [code]true[/code] as long as the key exists, even if the value is [code]null[/code]. Objects also receive notifications. Notifications are a simple way to notify the object about different events, so they can all be handled together. See [method _notification]. + [b]Note:[/b] Unlike references to a [Reference], references to an Object stored in a variable can become invalid without warning. Therefore, it's recommended to use [Reference] for data classes instead of [Object]. </description> <tutorials> + <link title="When and how to avoid using nodes for everything">https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html</link> </tutorials> <methods> <method name="_get" qualifiers="virtual"> @@ -518,7 +520,7 @@ One-shot connections disconnect themselves after emission. </constant> <constant name="CONNECT_REFERENCE_COUNTED" value="8" enum="ConnectFlags"> - Connect a signal as reference counted. This means that a given signal can be connected several times to the same target, and will only be fully disconnected once no references are left. + Connect a signal as reference-counted. This means that a given signal can be connected several times to the same target, and will only be fully disconnected once no references are left. </constant> </constants> </class> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index e255ce2e1a..f13dbbae76 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -244,7 +244,7 @@ <member name="audio/default_bus_layout" type="String" setter="" getter="" default=""res://default_bus_layout.tres""> Default [AudioBusLayout] resource file to use in the project, unless overridden by the scene. </member> - <member name="audio/driver" type="String" setter="" getter="" default=""PulseAudio""> + <member name="audio/driver" type="String" setter="" getter=""> Specifies the audio driver to use. This setting is platform-dependent as each platform supports different audio drivers. If left empty, the default audio driver will be used. </member> <member name="audio/enable_audio_input" type="bool" setter="" getter="" default="false"> @@ -280,6 +280,10 @@ <member name="debug/gdscript/completion/autocomplete_setters_and_getters" type="bool" setter="" getter="" default="false"> If [code]true[/code], displays getters and setters in autocompletion results in the script editor. This setting is meant to be used when porting old projects (Godot 2), as using member variables is the preferred style from Godot 3 onwards. </member> + <member name="debug/gdscript/warnings/assert_always_false" type="bool" setter="" getter="" default="true"> + </member> + <member name="debug/gdscript/warnings/assert_always_true" type="bool" setter="" getter="" default="true"> + </member> <member name="debug/gdscript/warnings/constant_used_as_function" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when a constant is used as a function. </member> @@ -292,15 +296,6 @@ <member name="debug/gdscript/warnings/exclude_addons" type="bool" setter="" getter="" default="true"> If [code]true[/code], scripts in the [code]res://addons[/code] folder will not generate warnings. </member> - <member name="debug/gdscript/warnings/function_conflicts_constant" type="bool" setter="" getter="" default="true"> - If [code]true[/code], enables warnings when a function is declared with the same name as a constant. - </member> - <member name="debug/gdscript/warnings/function_conflicts_variable" type="bool" setter="" getter="" default="true"> - If [code]true[/code], enables warnings when a function is declared with the same name as a variable. This will turn into an error in a future version when first-class functions become supported in GDScript. - </member> - <member name="debug/gdscript/warnings/function_may_yield" type="bool" setter="" getter="" default="true"> - If [code]true[/code], enables warnings when a function assigned to a variable may yield and return a function state instead of a value. - </member> <member name="debug/gdscript/warnings/function_used_as_property" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when using a function as if it was a property. </member> @@ -316,12 +311,16 @@ <member name="debug/gdscript/warnings/property_used_as_function" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when using a property as if it was a function. </member> + <member name="debug/gdscript/warnings/redundant_await" type="bool" setter="" getter="" default="true"> + </member> <member name="debug/gdscript/warnings/return_value_discarded" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when calling a function without using its return value (by assigning it to a variable or using it as a function argument). Such return values are sometimes used to denote possible errors using the [enum Error] enum. </member> <member name="debug/gdscript/warnings/shadowed_variable" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when defining a local or subclass member variable that would shadow a variable at an upper level (such as a member variable). </member> + <member name="debug/gdscript/warnings/shadowed_variable_base_class" type="bool" setter="" getter="" default="true"> + </member> <member name="debug/gdscript/warnings/standalone_expression" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when calling an expression that has no effect on the surrounding code, such as writing [code]2 + 2[/code] as a statement. </member> @@ -340,6 +339,8 @@ <member name="debug/gdscript/warnings/unreachable_code" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when unreachable code is detected (such as after a [code]return[/code] statement that will always be executed). </member> + <member name="debug/gdscript/warnings/unreachable_pattern" type="bool" setter="" getter="" default="true"> + </member> <member name="debug/gdscript/warnings/unsafe_call_argument" type="bool" setter="" getter="" default="false"> If [code]true[/code], enables warnings when using an expression whose type may not be compatible with the function parameter expected. </member> @@ -352,11 +353,11 @@ <member name="debug/gdscript/warnings/unsafe_property_access" type="bool" setter="" getter="" default="false"> If [code]true[/code], enables warnings when accessing a property whose presence is not guaranteed at compile-time in the class. </member> - <member name="debug/gdscript/warnings/unused_argument" type="bool" setter="" getter="" default="true"> - If [code]true[/code], enables warnings when a function parameter is unused. + <member name="debug/gdscript/warnings/unused_local_constant" type="bool" setter="" getter="" default="true"> </member> - <member name="debug/gdscript/warnings/unused_class_variable" type="bool" setter="" getter="" default="false"> - If [code]true[/code], enables warnings when a member variable is unused. + <member name="debug/gdscript/warnings/unused_parameter" type="bool" setter="" getter="" default="true"> + </member> + <member name="debug/gdscript/warnings/unused_private_class_variable" type="bool" setter="" getter="" default="true"> </member> <member name="debug/gdscript/warnings/unused_signal" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when a signal is unused. @@ -364,9 +365,6 @@ <member name="debug/gdscript/warnings/unused_variable" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when a local variable is unused. </member> - <member name="debug/gdscript/warnings/variable_conflicts_function" type="bool" setter="" getter="" default="true"> - If [code]true[/code], enables warnings when a variable is declared with the same name as a function. This will turn into an error in a future version when first-class functions become supported in GDScript. - </member> <member name="debug/gdscript/warnings/void_assignment" type="bool" setter="" getter="" default="true"> If [code]true[/code], enables warnings when assigning the result of a function that returns [code]void[/code] to a variable. </member> @@ -453,7 +451,7 @@ <member name="display/window/size/width" type="int" setter="" getter="" default="1024"> Sets the game's main viewport width. On desktop platforms, this is the default window size. Stretch mode settings also use this as a reference when enabled. </member> - <member name="display/window/tablet_driver" type="String" setter="" getter="" default=""""> + <member name="display/window/tablet_driver" type="String" setter="" getter=""> Specifies the tablet driver to use. If left empty, the default driver will be used. </member> <member name="display/window/vsync/use_vsync" type="bool" setter="" getter="" default="true"> @@ -472,7 +470,7 @@ <member name="gui/common/default_scroll_deadzone" type="int" setter="" getter="" default="0"> Default value for [member ScrollContainer.scroll_deadzone], which will be used for all [ScrollContainer]s unless overridden. </member> - <member name="gui/common/swap_cancel_ok" type="bool" setter="" getter="" default="false"> + <member name="gui/common/swap_cancel_ok" type="bool" setter="" getter=""> If [code]true[/code], swaps Cancel and OK buttons in dialogs on Windows and UWP to follow interface conventions. </member> <member name="gui/common/text_edit_undo_stack_max_size" type="int" setter="" getter="" default="1024"> diff --git a/doc/classes/Reference.xml b/doc/classes/Reference.xml index 860a47798c..9c3d1d5d9d 100644 --- a/doc/classes/Reference.xml +++ b/doc/classes/Reference.xml @@ -5,10 +5,11 @@ </brief_description> <description> Base class for any object that keeps a reference count. [Resource] and many other helper objects inherit this class. - References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with [method Object.free]. + Unlike [Object]s, References keep an internal reference counter so that they are automatically released when no longer in use, and only then. References therefore do not need to be freed manually with [method Object.free]. In the vast majority of use cases, instantiating and using [Reference]-derived types is all you need to do. The methods provided in this class are only for advanced users, and can cause issues if misused. </description> <tutorials> + <link title="When and how to avoid using nodes for everything">https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html</link> </tutorials> <methods> <method name="init_ref"> diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 0aa40dffb3..e79a2e0ea9 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -4,10 +4,11 @@ Base class for all resources. </brief_description> <description> - Resource is the base class for all Godot-specific resource types, serving primarily as data containers. They are reference counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. + Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Unlike [Object]s, they are reference-counted and freed when no longer in use. They are also cached once loaded from disk, so that any further attempts to load a resource from a given path will return the same reference (all this in contrast to a [Node], which is not reference-counted and can be instanced from disk as many times as desired). Resources can be saved externally on disk or bundled into another object, such as a [Node] or another resource. </description> <tutorials> - <link>https://docs.godotengine.org/en/latest/getting_started/step_by_step/resources.html</link> + <link title="Resources">https://docs.godotengine.org/en/latest/getting_started/step_by_step/resources.html</link> + <link title="When and how to avoid using nodes for everything">https://docs.godotengine.org/en/latest/getting_started/workflow/best_practices/node_alternatives.html</link> </tutorials> <methods> <method name="_setup_local_to_scene" qualifiers="virtual"> diff --git a/doc/classes/RigidBody2D.xml b/doc/classes/RigidBody2D.xml index d56dc1e17c..a7efba518c 100644 --- a/doc/classes/RigidBody2D.xml +++ b/doc/classes/RigidBody2D.xml @@ -84,7 +84,7 @@ <return type="Node2D[]"> </return> <description> - Returns a list of the bodies colliding with this one. Use [member contacts_reported] to set the maximum number reported. You must also set [member contact_monitor] to [code]true[/code]. + Returns a list of the bodies colliding with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [b]Note:[/b] The result of this test is not immediate after moving objects. For performance, list of collisions is updated once per frame and before the physics step. Consider using signals instead. </description> </method> @@ -133,7 +133,8 @@ If [code]true[/code], the body will emit signals when it collides with another RigidBody2D. See also [member contacts_reported]. </member> <member name="contacts_reported" type="int" setter="set_max_contacts_reported" getter="get_max_contacts_reported" default="0"> - The maximum number of contacts to report. + The maximum number of contacts that will be recorded. Requires [member contact_monitor] to be set to [code]true[/code]. + [b]Note:[/b] The number of contacts is different from the number of collisions. Collisions between parallel edges will result in two contacts (one at each end), and collisions between parallel faces will result in four contacts (one at each corner). </member> <member name="continuous_cd" type="int" setter="set_continuous_collision_detection_mode" getter="get_continuous_collision_detection_mode" enum="RigidBody2D.CCDMode" default="0"> Continuous collision detection mode. @@ -176,14 +177,14 @@ <argument index="0" name="body" type="Node"> </argument> <description> - Emitted when a body enters into contact with this one. [member contact_monitor] must be [code]true[/code] and [member contacts_reported] greater than [code]0[/code]. + Emitted when a body enters into contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. </description> </signal> <signal name="body_exited"> <argument index="0" name="body" type="Node"> </argument> <description> - Emitted when a body exits contact with this one. [member contact_monitor] must be [code]true[/code] and [member contacts_reported] greater than [code]0[/code]. + Emitted when a body exits contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. </description> </signal> <signal name="body_shape_entered"> @@ -196,7 +197,7 @@ <argument index="3" name="local_shape" type="int"> </argument> <description> - Emitted when a body enters into contact with this one. Reports colliding shape information. See [CollisionObject2D] for shape index information. [member contact_monitor] must be [code]true[/code] and [member contacts_reported] greater than [code]0[/code]. + Emitted when a body enters into contact with this one. Reports colliding shape information. See [CollisionObject2D] for shape index information. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. </description> </signal> <signal name="body_shape_exited"> @@ -209,7 +210,7 @@ <argument index="3" name="local_shape" type="int"> </argument> <description> - Emitted when a body shape exits contact with this one. Reports colliding shape information. See [CollisionObject2D] for shape index information. [member contact_monitor] must be [code]true[/code] and [member contacts_reported] greater than [code]0[/code]. + Emitted when a body shape exits contact with this one. Reports colliding shape information. See [CollisionObject2D] for shape index information. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. </description> </signal> <signal name="sleeping_state_changed"> diff --git a/doc/classes/RigidBody3D.xml b/doc/classes/RigidBody3D.xml index 370e6bd19c..933885ba77 100644 --- a/doc/classes/RigidBody3D.xml +++ b/doc/classes/RigidBody3D.xml @@ -96,7 +96,7 @@ <return type="Array"> </return> <description> - Returns a list of the bodies colliding with this one. By default, number of max contacts reported is at 0, see the [member contacts_reported] property to increase it. + Returns a list of the bodies colliding with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. [b]Note:[/b] The result of this test is not immediate after moving objects. For performance, list of collisions is updated once per frame and before the physics step. Consider using signals instead. </description> </method> @@ -157,10 +157,11 @@ If [code]true[/code], the body can enter sleep mode when there is no movement. See [member sleeping]. </member> <member name="contact_monitor" type="bool" setter="set_contact_monitor" getter="is_contact_monitor_enabled" default="false"> - If [code]true[/code], the RigidBody3D will emit signals when it collides with another RigidBody3D. + If [code]true[/code], the RigidBody3D will emit signals when it collides with another RigidBody3D. See also [member contacts_reported]. </member> <member name="contacts_reported" type="int" setter="set_max_contacts_reported" getter="get_max_contacts_reported" default="0"> - The maximum contacts to report. Bodies can keep a log of the contacts with other bodies, this is enabled by setting the maximum amount of contacts reported to a number greater than 0. + The maximum number of contacts that will be recorded. Requires [member contact_monitor] to be set to [code]true[/code]. + [b]Note:[/b] The number of contacts is different from the number of collisions. Collisions between parallel edges will result in two contacts (one at each end), and collisions between parallel faces will result in four contacts (one at each corner). </member> <member name="continuous_cd" type="bool" setter="set_use_continuous_collision_detection" getter="is_using_continuous_collision_detection" default="false"> If [code]true[/code], continuous collision detection is used. @@ -200,14 +201,14 @@ <argument index="0" name="body" type="Node"> </argument> <description> - Emitted when a body enters into contact with this one. Contact monitor and contacts reported must be enabled for this to work. + Emitted when a body enters into contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. </description> </signal> <signal name="body_exited"> <argument index="0" name="body" type="Node"> </argument> <description> - Emitted when a body shape exits contact with this one. Contact monitor and contacts reported must be enabled for this to work. + Emitted when a body shape exits contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. </description> </signal> <signal name="body_shape_entered"> @@ -220,7 +221,7 @@ <argument index="3" name="local_shape" type="int"> </argument> <description> - Emitted when a body enters into contact with this one. Contact monitor and contacts reported must be enabled for this to work. + Emitted when a body enters into contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. This signal not only receives the body that collided with this one, but also its [RID] ([code]body_id[/code]), the shape index from the colliding body ([code]body_shape[/code]), and the shape index from this body ([code]local_shape[/code]) the other body collided with. </description> </signal> @@ -234,7 +235,7 @@ <argument index="3" name="local_shape" type="int"> </argument> <description> - Emitted when a body shape exits contact with this one. Contact monitor and contacts reported must be enabled for this to work. + Emitted when a body shape exits contact with this one. Requires [member contact_monitor] to be set to [code]true[/code] and [member contacts_reported] to be set high enough to detect all the collisions. This signal not only receives the body that stopped colliding with this one, but also its [RID] ([code]body_id[/code]), the shape index from the colliding body ([code]body_shape[/code]), and the shape index from this body ([code]local_shape[/code]) the other body stopped colliding with. </description> </signal> diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index 050d7056af..7ec8fe12fb 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -263,7 +263,7 @@ <argument index="1" name="pose" type="Transform"> </argument> <description> - Returns the pose transform for bone [code]bone_idx[/code]. + Sets the pose transform for bone [code]bone_idx[/code]. [b]Note[/b]: The pose transform needs to be in bone space. Use [method world_transform_to_bone_transform] to convert a world transform, like one you can get from a [Node3D], to bone space. </description> </method> diff --git a/doc/classes/SpringArm3D.xml b/doc/classes/SpringArm3D.xml index 8305494c2b..15caff9eeb 100644 --- a/doc/classes/SpringArm3D.xml +++ b/doc/classes/SpringArm3D.xml @@ -32,7 +32,7 @@ <return type="float"> </return> <description> - Returns the proportion between the current arm length (after checking for collisions) and the [member spring_length]. Ranges from 0 to 1. + Returns the spring arm's current length. </description> </method> <method name="remove_excluded_object"> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 71db03e84f..ded64761d0 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -4,7 +4,7 @@ Built-in string class. </brief_description> <description> - This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference counted and use a copy-on-write approach, so passing them around is cheap in resources. + This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference-counted and use a copy-on-write approach, so passing them around is cheap in resources. </description> <tutorials> <link>https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_format_string.html</link> @@ -895,8 +895,8 @@ <argument index="2" name="maxsplit" type="int" default="0"> </argument> <description> - Splits the string by a [code]delimiter[/code] string and returns an array of the substrings. - If [code]maxsplit[/code] is specified, it defines the number of splits to do from the left up to [code]maxsplit[/code]. The default value of 0 means that all items are split. + Splits the string by a [code]delimiter[/code] string and returns an array of the substrings. The [code]delimiter[/code] can be of any length. + If [code]maxsplit[/code] is specified, it defines the number of splits to do from the left up to [code]maxsplit[/code]. The default value of [code]0[/code] means that all items are split. Example: [codeblock] var some_string = "One,Two,Three,Four" @@ -905,6 +905,7 @@ print(some_array[0]) # Prints "One" print(some_array[1]) # Prints "Two,Three,Four" [/codeblock] + If you need to split strings with more complex rules, use the [RegEx] class instead. </description> </method> <method name="split_floats"> diff --git a/doc/classes/Thread.xml b/doc/classes/Thread.xml index 4d6e89fa6f..5c63d01322 100644 --- a/doc/classes/Thread.xml +++ b/doc/classes/Thread.xml @@ -7,7 +7,8 @@ A unit of execution in a process. Can run methods on [Object]s simultaneously. The use of synchronization via [Mutex] or [Semaphore] is advised if working with shared objects. </description> <tutorials> - <link>https://docs.godotengine.org/en/latest/tutorials/threads/using_multiple_threads.html</link> + <link title="Using multiple threads">https://docs.godotengine.org/en/latest/tutorials/threads/using_multiple_threads.html</link> + <link title="Thread-safe APIs">https://docs.godotengine.org/en/latest/tutorials/threads/thread_safe_apis.html</link> </tutorials> <methods> <method name="get_id" qualifiers="const"> diff --git a/doc/classes/TileSet.xml b/doc/classes/TileSet.xml index 9a78e45d46..4991a1e58b 100644 --- a/doc/classes/TileSet.xml +++ b/doc/classes/TileSet.xml @@ -478,7 +478,17 @@ <argument index="0" name="id" type="int"> </argument> <description> - Returns an array of the tile's shapes. + Returns an array of dictionaries describing the tile's shapes. + [b]Dictionary structure in the array returned by this method:[/b] + [codeblock] + { + "autotile_coord": Vector2, + "one_way": bool, + "one_way_margin": int, + "shape": CollisionShape2D, + "shape_transform": Transform2D, + } + [/codeblock] </description> </method> <method name="tile_get_texture" qualifiers="const"> diff --git a/doc/classes/VisualShaderNodeBooleanUniform.xml b/doc/classes/VisualShaderNodeBooleanUniform.xml index 8313a8256e..7d72f13f9d 100644 --- a/doc/classes/VisualShaderNodeBooleanUniform.xml +++ b/doc/classes/VisualShaderNodeBooleanUniform.xml @@ -10,6 +10,14 @@ </tutorials> <methods> </methods> + <members> + <member name="default_value" type="bool" setter="set_default_value" getter="get_default_value" default="false"> + A default value to be assigned within the shader. + </member> + <member name="default_value_enabled" type="bool" setter="set_default_value_enabled" getter="is_default_value_enabled" default="false"> + Enables usage of the [member default_value]. + </member> + </members> <constants> </constants> </class> diff --git a/doc/classes/VisualShaderNodeColorUniform.xml b/doc/classes/VisualShaderNodeColorUniform.xml index 6972ccefd9..90ef381b76 100644 --- a/doc/classes/VisualShaderNodeColorUniform.xml +++ b/doc/classes/VisualShaderNodeColorUniform.xml @@ -10,6 +10,14 @@ </tutorials> <methods> </methods> + <members> + <member name="default_value" type="Color" setter="set_default_value" getter="get_default_value" default="Color( 1, 1, 1, 1 )"> + A default value to be assigned within the shader. + </member> + <member name="default_value_enabled" type="bool" setter="set_default_value_enabled" getter="is_default_value_enabled" default="false"> + Enables usage of the [member default_value]. + </member> + </members> <constants> </constants> </class> diff --git a/doc/classes/VisualShaderNodeFloatUniform.xml b/doc/classes/VisualShaderNodeFloatUniform.xml index 33ece8ac1b..705d5e8796 100644 --- a/doc/classes/VisualShaderNodeFloatUniform.xml +++ b/doc/classes/VisualShaderNodeFloatUniform.xml @@ -11,6 +11,12 @@ <methods> </methods> <members> + <member name="default_value" type="float" setter="set_default_value" getter="get_default_value" default="0.0"> + A default value to be assigned within the shader. + </member> + <member name="default_value_enabled" type="bool" setter="set_default_value_enabled" getter="is_default_value_enabled" default="false"> + Enables usage of the [member default_value]. + </member> <member name="hint" type="int" setter="set_hint" getter="get_hint" enum="VisualShaderNodeFloatUniform.Hint" default="0"> A hint applied to the uniform, which controls the values it can take when set through the inspector. </member> diff --git a/doc/classes/VisualShaderNodeIntUniform.xml b/doc/classes/VisualShaderNodeIntUniform.xml index 8c7c288177..e39eba865b 100644 --- a/doc/classes/VisualShaderNodeIntUniform.xml +++ b/doc/classes/VisualShaderNodeIntUniform.xml @@ -11,6 +11,12 @@ <methods> </methods> <members> + <member name="default_value" type="int" setter="set_default_value" getter="get_default_value" default="0"> + A default value to be assigned within the shader. + </member> + <member name="default_value_enabled" type="bool" setter="set_default_value_enabled" getter="is_default_value_enabled" default="false"> + Enables usage of the [member default_value]. + </member> <member name="hint" type="int" setter="set_hint" getter="get_hint" enum="VisualShaderNodeIntUniform.Hint" default="0"> A hint applied to the uniform, which controls the values it can take when set through the inspector. </member> diff --git a/doc/classes/VisualShaderNodeTransformUniform.xml b/doc/classes/VisualShaderNodeTransformUniform.xml index 43696c8226..ff6246618d 100644 --- a/doc/classes/VisualShaderNodeTransformUniform.xml +++ b/doc/classes/VisualShaderNodeTransformUniform.xml @@ -10,6 +10,14 @@ </tutorials> <methods> </methods> + <members> + <member name="default_value" type="Transform" setter="set_default_value" getter="get_default_value" default="Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )"> + A default value to be assigned within the shader. + </member> + <member name="default_value_enabled" type="bool" setter="set_default_value_enabled" getter="is_default_value_enabled" default="false"> + Enables usage of the [member default_value]. + </member> + </members> <constants> </constants> </class> diff --git a/doc/classes/VisualShaderNodeUniformRef.xml b/doc/classes/VisualShaderNodeUniformRef.xml new file mode 100644 index 0000000000..db02e398ab --- /dev/null +++ b/doc/classes/VisualShaderNodeUniformRef.xml @@ -0,0 +1,20 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="VisualShaderNodeUniformRef" inherits="VisualShaderNode" version="4.0"> + <brief_description> + A reference to an existing [VisualShaderNodeUniform]. + </brief_description> + <description> + Creating a reference to a [VisualShaderNodeUniform] allows you to reuse this uniform in different shaders or shader stages easily. + </description> + <tutorials> + </tutorials> + <methods> + </methods> + <members> + <member name="uniform_name" type="String" setter="set_uniform_name" getter="get_uniform_name" default=""[None]""> + The name of the uniform which this reference points to. + </member> + </members> + <constants> + </constants> +</class> diff --git a/doc/classes/VisualShaderNodeVec3Uniform.xml b/doc/classes/VisualShaderNodeVec3Uniform.xml index c8b44fdc8d..cd1500f5a1 100644 --- a/doc/classes/VisualShaderNodeVec3Uniform.xml +++ b/doc/classes/VisualShaderNodeVec3Uniform.xml @@ -10,6 +10,14 @@ </tutorials> <methods> </methods> + <members> + <member name="default_value" type="Vector3" setter="set_default_value" getter="get_default_value" default="Vector3( 0, 0, 0 )"> + A default value to be assigned within the shader. + </member> + <member name="default_value_enabled" type="bool" setter="set_default_value_enabled" getter="is_default_value_enabled" default="false"> + Enables usage of the [member default_value]. + </member> + </members> <constants> </constants> </class> diff --git a/doc/tools/makerst.py b/doc/tools/makerst.py index c0bba38799..25e5cb5367 100755 --- a/doc/tools/makerst.py +++ b/doc/tools/makerst.py @@ -565,6 +565,8 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S index += 1 + f.write(make_footer()) + def escape_rst(text, until_pos=-1): # type: (str) -> str # Escape \ character, otherwise it ends up as an escape character in rst @@ -995,7 +997,10 @@ def make_method_signature( out += " **)**" if isinstance(method_def, MethodDef) and method_def.qualifiers is not None: - out += " " + method_def.qualifiers + # Use substitutions for abbreviations. This is used to display tooltips on hover. + # See `make_footer()` for descriptions. + for qualifier in method_def.qualifiers.split(): + out += " |" + qualifier + "|" return ret_type, out @@ -1004,6 +1009,18 @@ def make_heading(title, underline): # type: (str, str) -> str return title + "\n" + (underline * len(title)) + "\n\n" +def make_footer(): # type: () -> str + # Generate reusable abbreviation substitutions. + # This way, we avoid bloating the generated rST with duplicate abbreviations. + # fmt: off + return ( + ".. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`\n" + ".. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`\n" + ".. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`" + ) + # fmt: on + + def make_url(link): # type: (str) -> str match = GODOT_DOCS_PATTERN.search(link) if match: |