diff options
Diffstat (limited to 'doc/classes')
27 files changed, 392 insertions, 113 deletions
diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index cea5360234..8fb688a8ae 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -197,7 +197,7 @@ </argument> <description> Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a [code]before[/code] specifier can be passed. If [code]false[/code], the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return [code]true[/code] if the first argument is less than the second, and return [code]false[/code] otherwise. - [b]Note:[/b] Calling [method bsearch] on an unsorted array results in unexpected behavior. + [b]Note:[/b] Calling [method bsearch_custom] on an unsorted array results in unexpected behavior. </description> </method> <method name="clear"> diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml index f137ede90f..b69768d33f 100644 --- a/doc/classes/Callable.xml +++ b/doc/classes/Callable.xml @@ -8,26 +8,26 @@ [b]Example:[/b] [codeblocks] [gdscript] - var callable = Callable(self, "print_args") func print_args(arg1, arg2, arg3 = ""): prints(arg1, arg2, arg3) func test(): - callable.call("hello", "world") # Prints "hello world". + var callable = Callable(self, "print_args") + callable.call("hello", "world") # Prints "hello world ". callable.call(Vector2.UP, 42, callable) # Prints "(0, -1) 42 Node(Node.gd)::print_args". callable.call("invalid") # Invalid call, should have at least 2 arguments. [/gdscript] [csharp] - Callable callable = new Callable(this, "print_args"); - public void PrintArgs(object arg1, object arg2, object arg3 = "") + public void PrintArgs(object arg1, object arg2, object arg3 = null) { GD.PrintS(arg1, arg2, arg3); } public void Test() { - callable.Call("hello", "world"); // Prints "hello world". - callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.gd)::print_args". + Callable callable = new Callable(this, nameof(PrintArgs)); + callable.Call("hello", "world"); // Prints "hello world null". + callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs". callable.Call("invalid"); // Invalid call, should have at least 2 arguments. } [/csharp] @@ -67,6 +67,7 @@ <return type="Callable"> </return> <description> + Returns a copy of this [Callable] with the arguments bound. Bound arguments are passed after the arguments supplied by [method call]. </description> </method> <method name="call" qualifiers="vararg"> @@ -108,24 +109,28 @@ <return type="int"> </return> <description> + Returns the hash value of this [Callable]'s object. </description> </method> <method name="is_custom"> <return type="bool"> </return> <description> + Returns [code]true[/code] if this [Callable] is a custom callable whose behavior differs based on implementation details. Custom callables are used in the engine for various reasons. If [code]true[/code], you can't use [method get_method]. </description> </method> <method name="is_null"> <return type="bool"> </return> <description> + Returns [code]true[/code] if this [Callable] has no target to call the method on. </description> </method> <method name="is_standard"> <return type="bool"> </return> <description> + Returns [code]true[/code] if this [Callable] is a standard callable, referencing an object and a method using a [StringName]. </description> </method> <method name="operator !=" qualifiers="operator"> @@ -134,6 +139,7 @@ <argument index="0" name="right" type="Callable"> </argument> <description> + Returns [code]true[/code] if both [Callable]s invoke different targets. </description> </method> <method name="operator ==" qualifiers="operator"> @@ -142,6 +148,7 @@ <argument index="0" name="right" type="Callable"> </argument> <description> + Returns [code]true[/code] if both [Callable]s invoke the same custom target. </description> </method> <method name="unbind"> @@ -150,6 +157,7 @@ <argument index="0" name="argcount" type="int"> </argument> <description> + Returns a copy of this [Callable] with the arguments unbound. Calling the returned [Callable] will call the method without the extra arguments that are supplied in the [Callable] on which you are calling this method. </description> </method> </methods> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index e5285587eb..c5e820e9fe 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -869,7 +869,7 @@ <argument index="0" name="control" type="Control"> </argument> <description> - Shows the given control at the mouse pointer. A good time to call this method is in [method get_drag_data]. The control must not be in the scene tree. + Shows the given control at the mouse pointer. A good time to call this method is in [method get_drag_data]. The control must not be in the scene tree. You should not free the control, and you should not keep a reference to the control beyond the duration of the drag. It will be deleted automatically after the drag has ended. [codeblocks] [gdscript] export (Color, RGBA) var color = Color(1, 0, 0, 1) diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml index 2d50d98a74..b33f3b4ffc 100644 --- a/doc/classes/Curve2D.xml +++ b/doc/classes/Curve2D.xml @@ -63,7 +63,7 @@ <argument index="0" name="to_point" type="Vector2"> </argument> <description> - Returns the closest point (in curve's local space) to [code]to_point[/code]. + Returns the closest baked point (in curve's local space) to [code]to_point[/code]. [code]to_point[/code] must be in this curve's local space. </description> </method> diff --git a/doc/classes/Curve3D.xml b/doc/classes/Curve3D.xml index bda04f010b..fcd150ad57 100644 --- a/doc/classes/Curve3D.xml +++ b/doc/classes/Curve3D.xml @@ -78,7 +78,7 @@ <argument index="0" name="to_point" type="Vector3"> </argument> <description> - Returns the closest point (in curve's local space) to [code]to_point[/code]. + Returns the closest baked point (in curve's local space) to [code]to_point[/code]. [code]to_point[/code] must be in this curve's local space. </description> </method> diff --git a/doc/classes/ItemList.xml b/doc/classes/ItemList.xml index ffeb45907d..0020cbf242 100644 --- a/doc/classes/ItemList.xml +++ b/doc/classes/ItemList.xml @@ -302,16 +302,7 @@ <argument index="1" name="custom_bg_color" type="Color"> </argument> <description> - [codeblocks] - [gdscript] - var itemList = ItemList.new() - some_string.set_item_custom_bg_color(0, Color.red) # This will set the background color of the first item of the control to red. - [/gdscript] - [csharp] - var itemList = new ItemList(); - itemList.SetItemCustomBgColor(0, Colors.Red); // This will set the background color of the first item of the control to red. - [/csharp] - [/codeblocks] + Sets the background color of the item specified by [code]idx[/code] index to the specified [Color]. </description> </method> <method name="set_item_custom_fg_color"> @@ -323,16 +314,6 @@ </argument> <description> Sets the foreground color of the item specified by [code]idx[/code] index to the specified [Color]. - [codeblocks] - [gdscript] - var item_list = ItemList.new() - item_list.set_item_custom_fg_color(0, Color.red) # This will set the foreground color of the first item of the control to red. - [/gdscript] - [csharp] - var itemList = new ItemList(); - itemList.SetItemCustomFgColor(0, Colors.Red); // This will set the foreground color of the first item of the control to red. - [/csharp] - [/codeblocks] </description> </method> <method name="set_item_disabled"> diff --git a/doc/classes/MarginContainer.xml b/doc/classes/MarginContainer.xml index c8eebd4677..a51632d5f1 100644 --- a/doc/classes/MarginContainer.xml +++ b/doc/classes/MarginContainer.xml @@ -5,21 +5,23 @@ </brief_description> <description> Adds a top, left, bottom, and right margin to all [Control] nodes that are direct children of the container. To control the [MarginContainer]'s margin, use the [code]margin_*[/code] theme properties listed below. - [b]Note:[/b] Be careful, [Control] margin values are different than the constant margin values. If you want to change the custom margin values of the [MarginContainer] by code, you should use the following examples: + [b]Note:[/b] Be careful, [Control] margin values are different from the constant margin values. If you want to change the custom margin values of the [MarginContainer] by code, you should use the following examples: [codeblocks] [gdscript] + # This code sample assumes the current script is extending MarginContainer. var margin_value = 100 - set("custom_constants/margin_top", margin_value) - set("custom_constants/margin_left", margin_value) - set("custom_constants/margin_bottom", margin_value) - set("custom_constants/margin_right", margin_value) + add_theme_constant_override("margin_top", margin_value) + add_theme_constant_override("margin_left", margin_value) + add_theme_constant_override("margin_bottom", margin_value) + add_theme_constant_override("margin_right", margin_value) [/gdscript] [csharp] + // This code sample assumes the current script is extending MarginContainer. int marginValue = 100; - Set("custom_constants/margin_top", marginValue); - Set("custom_constants/margin_left", marginValue); - Set("custom_constants/margin_bottom", marginValue); - Set("custom_constants/margin_right", marginValue); + AddThemeConstantOverride("margin_top", marginValue); + AddThemeConstantOverride("margin_left", marginValue); + AddThemeConstantOverride("margin_bottom", marginValue); + AddThemeConstantOverride("margin_right", marginValue); [/csharp] [/codeblocks] </description> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index f6602d5f4d..057a2b8d1a 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -207,10 +207,11 @@ <method name="get_environment" qualifiers="const"> <return type="String"> </return> - <argument index="0" name="environment" type="String"> + <argument index="0" name="variable" type="String"> </argument> <description> - Returns an environment variable. + Returns the value of an environment variable. Returns an empty string if the environment variable doesn't exist. + [b]Note:[/b] Double-check the casing of [code]variable[/code]. Environment variable names are case-sensitive on all platforms except Windows. </description> </method> <method name="get_executable_path" qualifiers="const"> @@ -383,10 +384,11 @@ <method name="has_environment" qualifiers="const"> <return type="bool"> </return> - <argument index="0" name="environment" type="String"> + <argument index="0" name="variable" type="String"> </argument> <description> - Returns [code]true[/code] if an environment variable exists. + Returns [code]true[/code] if the environment variable with the name [code]variable[/code] exists. + [b]Note:[/b] Double-check the casing of [code]variable[/code]. Environment variable names are case-sensitive on all platforms except Windows. </description> </method> <method name="has_feature" qualifiers="const"> @@ -501,6 +503,18 @@ [b]Note:[/b] This method is implemented on Android. </description> </method> + <method name="set_environment" qualifiers="const"> + <return type="bool"> + </return> + <argument index="0" name="variable" type="String"> + </argument> + <argument index="1" name="value" type="String"> + </argument> + <description> + Sets the value of the environment variable [code]variable[/code] to [code]value[/code]. The environment variable will be set for the Godot process and any process executed with [method execute] after running [method set_environment]. The environment variable will [i]not[/i] persist to processes run after the Godot process was terminated. + [b]Note:[/b] Double-check the casing of [code]variable[/code]. Environment variable names are case-sensitive on all platforms except Windows. + </description> + </method> <method name="set_thread_name"> <return type="int" enum="Error"> </return> @@ -535,10 +549,6 @@ </method> </methods> <members> - <member name="exit_code" type="int" setter="set_exit_code" getter="get_exit_code" default="0"> - The exit code passed to the OS when the main loop exits. By convention, an exit code of [code]0[/code] indicates success whereas a non-zero exit code indicates an error. For portability reasons, the exit code should be set between 0 and 125 (inclusive). - [b]Note:[/b] This value will be ignored if using [method SceneTree.quit] with an [code]exit_code[/code] argument passed. - </member> <member name="low_processor_usage_mode" type="bool" setter="set_low_processor_usage_mode" getter="is_in_low_processor_usage_mode" default="false"> If [code]true[/code], the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile. </member> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 5d29526ee1..03a88fd86c 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -274,9 +274,11 @@ If [code]true[/code], flushes the standard output stream every time a line is printed. This affects both terminal logging and file logging. When running a project, this setting must be enabled if you want logs to be collected by service managers such as systemd/journalctl. This setting is disabled by default on release builds, since flushing on every printed line will negatively affect performance if lots of lines are printed in a rapid succession. Also, if this setting is enabled, logged files will still be written successfully if the application crashes or is otherwise killed by the user (without being closed "normally"). [b]Note:[/b] Regardless of this setting, the standard error stream ([code]stderr[/code]) is always flushed when a line is printed to it. + Changes to this setting will only be applied upon restarting the application. </member> <member name="application/run/flush_stdout_on_print.debug" type="bool" setter="" getter="" default="true"> Debug build override for [member application/run/flush_stdout_on_print], as performance is less important during debugging. + Changes to this setting will only be applied upon restarting the application. </member> <member name="application/run/frame_delay_msec" type="int" setter="" getter="" default="0"> Forces a delay between frames in the main loop (in milliseconds). This may be useful if you plan to disable vertical synchronization. @@ -461,6 +463,9 @@ <member name="debug/shapes/collision/contact_color" type="Color" setter="" getter="" default="Color( 1, 0.2, 0.1, 0.8 )"> Color of the contact points between collision shapes, visible when "Visible Collision Shapes" is enabled in the Debug menu. </member> + <member name="debug/shapes/collision/draw_2d_outlines" type="bool" setter="" getter="" default="true"> + Sets whether 2D physics will display collision outlines in game when "Visible Collision Shapes" is enabled in the Debug menu. + </member> <member name="debug/shapes/collision/max_contacts_displayed" type="int" setter="" getter="" default="10000"> Maximum number of contact points between collision shapes to display when "Visible Collision Shapes" is enabled in the Debug menu. </member> diff --git a/doc/classes/RayCast3D.xml b/doc/classes/RayCast3D.xml index d24e86a08b..681cfcd4ce 100644 --- a/doc/classes/RayCast3D.xml +++ b/doc/classes/RayCast3D.xml @@ -136,6 +136,13 @@ <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1"> The ray's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See [url=https://docs.godotengine.org/en/latest/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information. </member> + <member name="debug_shape_custom_color" type="Color" setter="set_debug_shape__custom_color" getter="get_debug_shape_custom_color" default="Color( 0.0, 0.0, 0.0 )"> + The custom color to use to draw the shape in the editor and at run-time if [b]Visible Collision Shapes[/b] is enabled in the [b]Debug[/b] menu. This color will be highlighted at run-time if the [RayCast3D] is colliding with something. + If set to [code]Color(0.0, 0.0, 0.0)[/code] (by default), the color set in [member ProjectSettings.debug/shapes/collision/shape_color] is used. + </member> + <member name="debug_shape_thickness" type="int" setter="set_debug_shape_thickness" getter="get_debug_shape_thickness" default="1"> + If set to [code]1[/code], a line is used as the debug shape. Otherwise, a truncated pyramid is drawn to represent the [RayCast3D]. Requires [b]Visible Collision Shapes[/b] to be enabled in the [b]Debug[/b] menu for the debug shape to be visible at run-time. + </member> <member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true"> If [code]true[/code], collisions will be reported. </member> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index dfd4a5c2d5..d2b95fda20 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -2704,11 +2704,14 @@ <description> Copies the viewport to a region of the screen specified by [code]rect[/code]. If [method viewport_set_render_direct_to_screen] is [code]true[/code], then the viewport does not use a framebuffer and the contents of the viewport are rendered directly to screen. However, note that the root viewport is drawn last, therefore it will draw over the screen. Accordingly, you must set the root viewport to an area that does not cover the area that you have attached this viewport to. For example, you can set the root viewport to not render at all with the following code: - [codeblock] + FIXME: The method seems to be non-existent. + [codeblocks] + [gdscript] func _ready(): get_viewport().set_attach_to_screen_rect(Rect2()) $Viewport.set_attach_to_screen_rect(Rect2(0, 0, 600, 600)) - [/codeblock] + [/gdscript] + [/codeblocks] Using this can result in significant optimization, especially on lower-end devices. However, it comes at the cost of having to manage your viewports manually. For a further optimization see, [method viewport_set_render_direct_to_screen]. </description> </method> diff --git a/doc/classes/RichTextEffect.xml b/doc/classes/RichTextEffect.xml index 726b26fbc7..edab35f162 100644 --- a/doc/classes/RichTextEffect.xml +++ b/doc/classes/RichTextEffect.xml @@ -6,10 +6,16 @@ <description> A custom effect for use with [RichTextLabel]. [b]Note:[/b] For a [RichTextEffect] to be usable, a BBCode tag must be defined as a member variable called [code]bbcode[/code] in the script. - [codeblock] + [codeblocks] + [gdscript] # The RichTextEffect will be usable like this: `[example]Some text[/example]` var bbcode = "example" - [/codeblock] + [/gdscript] + [csharp] + // The RichTextEffect will be usable like this: `[example]Some text[/example]` + public string bbcode = "example"; + [/csharp] + [/codeblocks] [b]Note:[/b] As soon as a [RichTextLabel] contains at least one [RichTextEffect], it will continuously process the effect unless the project is paused. This may impact battery life negatively. </description> <tutorials> diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml index f65d013bfc..72a42202c7 100644 --- a/doc/classes/SceneTree.xml +++ b/doc/classes/SceneTree.xml @@ -69,12 +69,22 @@ <description> Returns a [SceneTreeTimer] which will [signal SceneTreeTimer.timeout] after the given time in seconds elapsed in this [SceneTree]. If [code]process_always[/code] is set to [code]false[/code], pausing the [SceneTree] will also pause the timer. Commonly used to create a one-shot delay timer as in the following example: - [codeblock] + [codeblocks] + [gdscript] func some_function(): print("start") yield(get_tree().create_timer(1.0), "timeout") print("end") - [/codeblock] + [/gdscript] + [csharp] + public async void SomeFunction() + { + GD.Print("start"); + await ToSignal(GetTree().CreateTimer(1.0f), "timeout"); + GD.Print("end"); + } + [/csharp] + [/codeblocks] The timer will be automatically freed after its time elapses. </description> </method> @@ -181,10 +191,12 @@ <method name="quit"> <return type="void"> </return> - <argument index="0" name="exit_code" type="int" default="-1"> + <argument index="0" name="exit_code" type="int" default="0"> </argument> <description> - Quits the application at the end of the current iteration. A process [code]exit_code[/code] can optionally be passed as an argument. If this argument is [code]0[/code] or greater, it will override the [member OS.exit_code] defined before quitting the application. + Quits the application at the end of the current iteration. Argument [code]exit_code[/code] can optionally be given (defaulting to 0) to customize the exit status code. + By convention, an exit code of [code]0[/code] indicates success whereas a non-zero exit code indicates an error. + For portability reasons, the exit code should be set between 0 and 125 (inclusive). </description> </method> <method name="reload_current_scene"> diff --git a/doc/classes/SceneTreeTimer.xml b/doc/classes/SceneTreeTimer.xml index a4a83fa65b..b223bf6821 100644 --- a/doc/classes/SceneTreeTimer.xml +++ b/doc/classes/SceneTreeTimer.xml @@ -6,12 +6,22 @@ <description> A one-shot timer managed by the scene tree, which emits [signal timeout] on completion. See also [method SceneTree.create_timer]. As opposed to [Timer], it does not require the instantiation of a node. Commonly used to create a one-shot delay timer as in the following example: - [codeblock] + [codeblocks] + [gdscript] func some_function(): print("Timer started.") yield(get_tree().create_timer(1.0), "timeout") print("Timer ended.") - [/codeblock] + [/gdscript] + [csharp] + public async void SomeFunction() + { + GD.Print("Timer started."); + await ToSignal(GetTree().CreateTimer(1.0f), "timeout"); + GD.Print("Timer ended."); + } + [/csharp] + [/codeblocks] </description> <tutorials> </tutorials> diff --git a/doc/classes/ScriptCreateDialog.xml b/doc/classes/ScriptCreateDialog.xml index aa60ecb12b..7185213c44 100644 --- a/doc/classes/ScriptCreateDialog.xml +++ b/doc/classes/ScriptCreateDialog.xml @@ -5,12 +5,24 @@ </brief_description> <description> The [ScriptCreateDialog] creates script files according to a given template for a given scripting language. The standard use is to configure its fields prior to calling one of the [method Window.popup] methods. - [codeblock] + [codeblocks] + [gdscript] func _ready(): - dialog.config("Node", "res://new_node.gd") # For in-engine types - dialog.config("\"res://base_node.gd\"", "res://derived_node.gd") # For script types + var dialog = ScriptCreateDialog.new(); + dialog.config("Node", "res://new_node.gd") # For in-engine types. + dialog.config("\"res://base_node.gd\"", "res://derived_node.gd") # For script types. dialog.popup_centered() - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + var dialog = new ScriptCreateDialog(); + dialog.Config("Node", "res://NewNode.cs"); // For in-engine types. + dialog.Config("\"res://BaseNode.cs\"", "res://DerivedNode.cs"); // For script types. + dialog.PopupCentered(); + } + [/csharp] + [/codeblocks] </description> <tutorials> </tutorials> diff --git a/doc/classes/SpinBox.xml b/doc/classes/SpinBox.xml index a08d4f5b44..7e2481f458 100644 --- a/doc/classes/SpinBox.xml +++ b/doc/classes/SpinBox.xml @@ -6,13 +6,22 @@ <description> SpinBox is a numerical input text field. It allows entering integers and floats. [b]Example:[/b] - [codeblock] + [codeblocks] + [gdscript] var spin_box = SpinBox.new() add_child(spin_box) var line_edit = spin_box.get_line_edit() line_edit.context_menu_enabled = false spin_box.align = LineEdit.ALIGN_RIGHT - [/codeblock] + [/gdscript] + [csharp] + var spinBox = new SpinBox(); + AddChild(spinBox); + var lineEdit = spinBox.GetLineEdit(); + lineEdit.ContextMenuEnabled = false; + spinBox.Align = LineEdit.AlignEnum.Right; + [/csharp] + [/codeblocks] The above code will create a [SpinBox], disable context menu on it and set the text alignment to right. See [Range] class for more options over the [SpinBox]. [b]Note:[/b] [SpinBox] relies on an underlying [LineEdit] node. To theme a [SpinBox]'s background, add theme items for [LineEdit] and customize them. diff --git a/doc/classes/Sprite2D.xml b/doc/classes/Sprite2D.xml index c56596423d..e4df753674 100644 --- a/doc/classes/Sprite2D.xml +++ b/doc/classes/Sprite2D.xml @@ -15,12 +15,29 @@ </return> <description> Returns a [Rect2] representing the Sprite2D's boundary in local coordinates. Can be used to detect if the Sprite2D was clicked. Example: - [codeblock] + [codeblocks] + [gdscript] func _input(event): if event is InputEventMouseButton and event.pressed and event.button_index == BUTTON_LEFT: if get_rect().has_point(to_local(event.position)): print("A click!") - [/codeblock] + [/gdscript] + [csharp] + public override void _Input(InputEvent inputEvent) + { + if (inputEvent is InputEventMouseButton inputEventMouse) + { + if (inputEventMouse.Pressed && inputEventMouse.ButtonIndex == (int)ButtonList.Left) + { + if (GetRect().HasPoint(ToLocal(inputEventMouse.Position))) + { + GD.Print("A click!"); + } + } + } + } + [/csharp] + [/codeblocks] </description> </method> <method name="is_pixel_opaque" qualifiers="const"> @@ -60,7 +77,7 @@ If [code]true[/code], texture is cut from a larger atlas texture. See [member region_rect]. </member> <member name="region_filter_clip" type="bool" setter="set_region_filter_clip" getter="is_region_filter_clip_enabled" default="false"> - If [code]true[/code], the outermost pixels get blurred out. + If [code]true[/code], the outermost pixels get blurred out. [member region_enabled] must be [code]true[/code]. </member> <member name="region_rect" type="Rect2" setter="set_region_rect" getter="get_region_rect" default="Rect2( 0, 0, 0, 0 )"> The region of the atlas texture to display. [member region_enabled] must be [code]true[/code]. diff --git a/doc/classes/StreamPeer.xml b/doc/classes/StreamPeer.xml index a73d3c8212..a1b858acf6 100644 --- a/doc/classes/StreamPeer.xml +++ b/doc/classes/StreamPeer.xml @@ -212,9 +212,14 @@ <description> Puts a zero-terminated ASCII string into the stream prepended by a 32-bit unsigned integer representing its size. Note: To put an ASCII string without prepending its size, you can use [method put_data]: - [codeblock] + [codeblocks] + [gdscript] put_data("Hello world".to_ascii()) - [/codeblock] + [/gdscript] + [csharp] + PutData("Hello World".ToAscii()); + [/csharp] + [/codeblocks] </description> </method> <method name="put_u16"> @@ -261,9 +266,14 @@ <description> Puts a zero-terminated UTF-8 string into the stream prepended by a 32 bits unsigned integer representing its size. Note: To put an UTF-8 string without prepending its size, you can use [method put_data]: - [codeblock] + [codeblocks] + [gdscript] put_data("Hello world".to_utf8()) - [/codeblock] + [/gdscript] + [csharp] + PutData("Hello World".ToUTF8()); + [/csharp] + [/codeblocks] </description> </method> <method name="put_var"> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index c03f6357ab..a90bcd9eb7 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -163,11 +163,15 @@ <description> Returns the index of the [b]first[/b] case-sensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the end of the string. [b]Note:[/b] If you just want to know whether a string contains a substring, use the [code]in[/code] operator as follows: - [codeblock] - # Will evaluate to `false`. - if "i" in "team": - pass - [/codeblock] + [codeblocks] + [gdscript] + print("i" in "team") # Will print `false`. + [/gdscript] + [csharp] + // C# has no in operator, but we can use `Contains()`. + GD.Print("team".Contains("i")); // Will print `false`. + [/csharp] + [/codeblocks] </description> </method> <method name="findn"> @@ -354,9 +358,14 @@ <description> Return a [String] which is the concatenation of the [code]parts[/code]. The separator between elements is the string providing this method. Example: - [codeblock] + [codeblocks] + [gdscript] print(", ".join(["One", "Two", "Three", "Four"])) - [/codeblock] + [/gdscript] + [csharp] + GD.Print(String.Join(",", new string[] {"One", "Two", "Three", "Four"})); + [/csharp] + [/codeblocks] </description> </method> <method name="json_escape"> @@ -654,13 +663,18 @@ The splits in the returned array are sorted in the same order as the original string, from left to right. If [code]maxsplit[/code] is specified, it defines the number of splits to do from the right up to [code]maxsplit[/code]. The default value of 0 means that all items are split, thus giving the same result as [method split]. Example: - [codeblock] + [codeblocks] + [gdscript] var some_string = "One,Two,Three,Four" var some_array = some_string.rsplit(",", true, 1) print(some_array.size()) # Prints 2 print(some_array[0]) # Prints "Four" print(some_array[1]) # Prints "Three,Two,One" - [/codeblock] + [/gdscript] + [csharp] + // There is no Rsplit. + [/csharp] + [/codeblocks] </description> </method> <method name="rstrip"> @@ -723,13 +737,21 @@ 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] + [codeblocks] + [gdscript] var some_string = "One,Two,Three,Four" var some_array = some_string.split(",", true, 1) print(some_array.size()) # Prints 2 - print(some_array[0]) # Prints "One" - print(some_array[1]) # Prints "Two,Three,Four" - [/codeblock] + print(some_array[0]) # Prints "Four" + print(some_array[1]) # Prints "Three,Two,One" + [/gdscript] + [csharp] + var someString = "One,Two,Three,Four"; + var someArray = someString.Split(",", true); // This is as close as it gets to Godots API. + GD.Print(someArray[0]); // Prints "Four" + GD.Print(someArray[1]); // Prints "Three,Two,One" + [/csharp] + [/codeblocks] If you need to split strings with more complex rules, use the [RegEx] class instead. </description> </method> diff --git a/doc/classes/StyleBoxFlat.xml b/doc/classes/StyleBoxFlat.xml index 13ea7df294..d66ae210ec 100644 --- a/doc/classes/StyleBoxFlat.xml +++ b/doc/classes/StyleBoxFlat.xml @@ -4,12 +4,12 @@ Customizable [StyleBox] with a given set of parameters (no texture required). </brief_description> <description> - This [StyleBox] can be used to achieve all kinds of looks without the need of a texture. Those properties are customizable: + This [StyleBox] can be used to achieve all kinds of looks without the need of a texture. The following properties are customizable: - Color - Border width (individual width for each border) - Rounded corners (individual radius for each corner) - Shadow (with blur and offset) - Setting corner radius to high values is allowed. As soon as corners would overlap, the stylebox will switch to a relative system. Example: + Setting corner radius to high values is allowed. As soon as corners overlap, the stylebox will switch to a relative system. Example: [codeblock] height = 30 corner_radius_top_left = 50 @@ -178,8 +178,8 @@ Border width for the top border. </member> <member name="corner_detail" type="int" setter="set_corner_detail" getter="get_corner_detail" default="8"> - This sets the amount of vertices used for each corner. Higher values result in rounder corners but take more processing power to compute. When choosing a value, you should take the corner radius ([method set_corner_radius_all]) into account. - For corner radii smaller than 10, [code]4[/code] or [code]5[/code] should be enough. For corner radii smaller than 30, values between [code]8[/code] and [code]12[/code] should be enough. + This sets the number of vertices used for each corner. Higher values result in rounder corners but take more processing power to compute. When choosing a value, you should take the corner radius ([method set_corner_radius_all]) into account. + For corner radii less than 10, [code]4[/code] or [code]5[/code] should be enough. For corner radii less than 30, values between [code]8[/code] and [code]12[/code] should be enough. A corner detail of [code]1[/code] will result in chamfered corners instead of rounded corners, which is useful for some artistic effects. </member> <member name="corner_radius_bottom_left" type="int" setter="set_corner_radius" getter="get_corner_radius" default="0"> diff --git a/doc/classes/SurfaceTool.xml b/doc/classes/SurfaceTool.xml index 331de4284e..d145b4ce97 100644 --- a/doc/classes/SurfaceTool.xml +++ b/doc/classes/SurfaceTool.xml @@ -5,13 +5,22 @@ </brief_description> <description> The [SurfaceTool] is used to construct a [Mesh] by specifying vertex attributes individually. It can be used to construct a [Mesh] from a script. All properties except indices need to be added before calling [method add_vertex]. For example, to add vertex colors and UVs: - [codeblock] + [codeblocks] + [gdscript] var st = SurfaceTool.new() st.begin(Mesh.PRIMITIVE_TRIANGLES) st.set_color(Color(1, 0, 0)) st.set_uv(Vector2(0, 0)) st.set_vertex(Vector3(0, 0, 0)) - [/codeblock] + [/gdscript] + [csharp] + var st = new SurfaceTool(); + st.Begin(Mesh.PrimitiveType.Triangles); + st.SetColor(new Color(1, 0, 0)); + st.SetUv(new Vector2(0, 0)); + st.SetVertex(new Vector3(0, 0, 0)); + [/csharp] + [/codeblocks] The above [SurfaceTool] now contains one vertex of a triangle which has a UV coordinate and a specified [Color]. If another vertex were added without calling [method set_uv] or [method set_color], then the last values would be used. Vertex attributes must be passed [b]before[/b] calling [method add_vertex]. Failure to do so will result in an error when committing the vertex information to a mesh. Additionally, the attributes used before the first vertex is added determine the format of the mesh. For example, if you only add UVs to the first vertex, you cannot add color to any of the subsequent vertices. diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 1d50cd60e5..6232a4e146 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -402,13 +402,24 @@ <description> Perform a search inside the text. Search flags can be specified in the [enum SearchFlags] enum. Returns an empty [code]Dictionary[/code] if no result was found. Otherwise, returns a [code]Dictionary[/code] containing [code]line[/code] and [code]column[/code] entries, e.g: - [codeblock] - var result = search(key, flags, line, column) - if !result.is_empty(): + [codeblocks] + [gdscript] + var result = search("print", SEARCH_WHOLE_WORDS, 0, 0) + if !result.empty(): # Result found. var line_number = result.line var column_number = result.column - [/codeblock] + [/gdscript] + [csharp] + int[] result = Search("print", (uint)TextEdit.SearchFlags.WholeWords, 0, 0); + if (result.Length > 0) + { + // Result found. + int lineNumber = result[(int)TextEdit.SearchResult.Line]; + int columnNumber = result[(int)TextEdit.SearchResult.Column]; + } + [/csharp] + [/codeblocks] </description> </method> <method name="select"> diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index a12ef614e3..c0ee004ca6 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -172,12 +172,22 @@ [b]Note:[/b] Data such as navigation polygons and collision shapes are not immediately updated for performance reasons. If you need these to be immediately updated, you can call [method update_dirty_quadrants]. Overriding this method also overrides it internally, allowing custom logic to be implemented when tiles are placed/removed: - [codeblock] + [codeblocks] + [gdscript] func set_cell(x, y, tile, flip_x=false, flip_y=false, transpose=false, autotile_coord=Vector2()) # Write your custom logic here. # To call the default method: .set_cell(x, y, tile, flip_x, flip_y, transpose, autotile_coord) - [/codeblock] + [/gdscript] + [csharp] + public void SetCell(int x, int y, int tile, bool flipX = false, bool flipY = false, bool transpose = false, Vector2 autotileCoord = new Vector2()) + { + // Write your custom logic here. + // To call the default method: + base.SetCell(x, y, tile, flipX, flipY, transpose, autotileCoord); + } + [/csharp] + [/codeblocks] </description> </method> <method name="set_cellv"> diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index 8502707096..a09f1bf470 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -6,16 +6,30 @@ <description> This shows a tree of items that can be selected, expanded and collapsed. The tree can have multiple columns with custom controls like text editing, buttons and popups. It can be useful for structured displays and interactions. Trees are built via code, using [TreeItem] objects to create the structure. They have a single root but multiple roots can be simulated if a dummy hidden root is added. - [codeblock] + [codeblocks] + [gdscript] func _ready(): var tree = Tree.new() var root = tree.create_item() - tree.set_hide_root(true) + tree.hide_root = true var child1 = tree.create_item(root) var child2 = tree.create_item(root) var subchild1 = tree.create_item(child1) subchild1.set_text(0, "Subchild1") - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + var tree = new Tree(); + TreeItem root = tree.CreateItem(); + tree.HideRoot = true; + TreeItem child1 = tree.CreateItem(root); + TreeItem child2 = tree.CreateItem(root); + TreeItem subchild1 = tree.CreateItem(child1); + subchild1.SetText(0, "Subchild1"); + } + [/csharp] + [/codeblocks] To iterate over all the [TreeItem] objects in a [Tree] object, use [method TreeItem.get_next] and [method TreeItem.get_children] after getting the root through [method get_root]. You can use [method Object.free] on a [TreeItem] to remove it from the [Tree]. </description> <tutorials> @@ -152,13 +166,26 @@ </return> <description> Returns the currently edited item. Can be used with [signal item_edited] to get the item that was modified. - [codeblock] + [codeblocks] + [gdscript] func _ready(): $Tree.item_edited.connect(on_Tree_item_edited) func on_Tree_item_edited(): print($Tree.get_edited()) # This item just got edited (e.g. checked). - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + GetNode<Tree>("Tree").ItemEdited += OnTreeItemEdited; + } + + public void OnTreeItemEdited() + { + GD.Print(GetNode<Tree>("Tree").GetEdited()); // This item just got edited (e.g. checked). + } + [/csharp] + [/codeblocks] </description> </method> <method name="get_edited_column" qualifiers="const"> diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml index 56ccaaf383..b32bb1e2d9 100644 --- a/doc/classes/Tween.xml +++ b/doc/classes/Tween.xml @@ -7,13 +7,22 @@ Tweens are useful for animations requiring a numerical property to be interpolated over a range of values. The name [i]tween[/i] comes from [i]in-betweening[/i], an animation technique where you specify [i]keyframes[/i] and the computer interpolates the frames that appear between them. [Tween] is more suited than [AnimationPlayer] for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a [Tween] node; it would be difficult to do the same thing with an [AnimationPlayer] node. Here is a brief usage example that makes a 2D node move smoothly between two positions: - [codeblock] + [codeblocks] + [gdscript] var tween = get_node("Tween") tween.interpolate_property($Node2D, "position", Vector2(0, 0), Vector2(100, 100), 1, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT) tween.start() - [/codeblock] + [/gdscript] + [csharp] + var tween = GetNode<Tween>("Tween"); + tween.InterpolateProperty(GetNode<Node2D>("Node2D"), "position", + new Vector2(0, 0), new Vector2(100, 100), 1, + Tween.TransitionType.Linear, Tween.EaseType.InOut); + tween.Start(); + [/csharp] + [/codeblocks] Many methods require a property name, such as [code]"position"[/code] above. You can find the correct property name by hovering over the property in the Inspector. You can also provide the components of a property directly by using [code]"property:component"[/code] (eg. [code]position:x[/code]), where it would only apply to that particular component. Many of the methods accept [code]trans_type[/code] and [code]ease_type[/code]. The first accepts an [enum TransitionType] constant, and refers to the way the timing of the animation is handled (see [url=https://easings.net/]easings.net[/url] for some examples). The second accepts an [enum EaseType] constant, and controls where the [code]trans_type[/code] is applied to the interpolation (in the beginning, the end, or both). If you don't know which transition and easing to pick, you can try different [enum TransitionType] constants with [constant EASE_IN_OUT], and use the one that looks best. [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/tween_cheatsheet.png]Tween easing and transition types cheatsheet[/url] diff --git a/doc/classes/UDPServer.xml b/doc/classes/UDPServer.xml index aabfed85f0..0fc00f67f8 100644 --- a/doc/classes/UDPServer.xml +++ b/doc/classes/UDPServer.xml @@ -7,8 +7,9 @@ A simple server that opens a UDP socket and returns connected [PacketPeerUDP] upon receiving new packets. See also [method PacketPeerUDP.connect_to_host]. After starting the server ([method listen]), you will need to [method poll] it at regular intervals (e.g. inside [method Node._process]) for it to process new packets, delivering them to the appropriate [PacketPeerUDP], and taking new connections. Below a small example of how it can be used: - [codeblock] - # server.gd + [codeblocks] + [gdscript] + class_name Server extends Node var server := UDPServer.new() @@ -21,20 +22,57 @@ server.poll() # Important! if server.is_connection_available(): var peer : PacketPeerUDP = server.take_connection() - var pkt = peer.get_packet() + var packet = peer.get_packet() print("Accepted peer: %s:%s" % [peer.get_packet_ip(), peer.get_packet_port()]) - print("Received data: %s" % [pkt.get_string_from_utf8()]) + print("Received data: %s" % [packet.get_string_from_utf8()]) # Reply so it knows we received the message. - peer.put_packet(pkt) + peer.put_packet(packet) # Keep a reference so we can keep contacting the remote peer. peers.append(peer) for i in range(0, peers.size()): pass # Do something with the connected peers. + [/gdscript] + [csharp] + using Godot; + using System; + using System.Collections.Generic; - [/codeblock] - [codeblock] - # client.gd + public class Server : Node + { + public UDPServer Server = new UDPServer(); + public List<PacketPeerUDP> Peers = new List<PacketPeerUDP>(); + + public override void _Ready() + { + Server.Listen(4242); + } + + public override void _Process(float delta) + { + Server.Poll(); // Important! + if (Server.IsConnectionAvailable()) + { + PacketPeerUDP peer = Server.TakeConnection(); + byte[] packet = peer.GetPacket(); + GD.Print($"Accepted Peer: {peer.GetPacketIp()}:{peer.GetPacketPort()}"); + GD.Print($"Received Data: {packet.GetStringFromUTF8()}"); + // Reply so it knows we received the message. + peer.PutPacket(packet); + // Keep a reference so we can keep contacting the remote peer. + Peers.Add(peer); + } + foreach (var peer in Peers) + { + // Do something with the peers. + } + } + } + [/csharp] + [/codeblocks] + [codeblocks] + [gdscript] + class_name Client extends Node var udp := PacketPeerUDP.new() @@ -50,7 +88,37 @@ if udp.get_available_packet_count() > 0: print("Connected: %s" % udp.get_packet().get_string_from_utf8()) connected = true - [/codeblock] + [/gdscript] + [csharp] + using Godot; + using System; + + public class Client : Node + { + public PacketPeerUDP Udp = new PacketPeerUDP(); + public bool Connected = false; + + public override void _Ready() + { + Udp.ConnectToHost("127.0.0.1", 4242); + } + + public override void _Process(float delta) + { + if (!Connected) + { + // Try to contact server + Udp.PutPacket("The Answer Is..42!".ToUTF8()); + } + if (Udp.GetAvailablePacketCount() > 0) + { + GD.Print($"Connected: {Udp.GetPacket().GetStringFromUTF8()}"); + Connected = true; + } + } + } + [/csharp] + [/codeblocks] </description> <tutorials> </tutorials> diff --git a/doc/classes/UndoRedo.xml b/doc/classes/UndoRedo.xml index e8124d0e6a..a0330de4fa 100644 --- a/doc/classes/UndoRedo.xml +++ b/doc/classes/UndoRedo.xml @@ -7,7 +7,8 @@ Helper to manage undo/redo operations in the editor or custom tools. It works by registering methods and property changes inside "actions". Common behavior is to create an action, then add do/undo calls to functions or property changes, then committing the action. Here's an example on how to add an action to the Godot editor's own [UndoRedo], from a plugin: - [codeblock] + [codeblocks] + [gdscript] var undo_redo = get_undo_redo() # Method of EditorPlugin. func do_something(): @@ -24,7 +25,37 @@ undo_redo.add_do_property(node, "position", Vector2(100,100)) undo_redo.add_undo_property(node, "position", node.position) undo_redo.commit_action() - [/codeblock] + [/gdscript] + [csharp] + public UndoRedo UndoRedo; + + public override void _Ready() + { + UndoRedo = GetUndoRedo(); // Method of EditorPlugin. + } + + public void DoSomething() + { + // Put your code here. + } + + public void UndoSomething() + { + // Put here the code that reverts what's done by "DoSomething()". + } + + private void OnMyButtonPressed() + { + var node = GetNode<Node2D>("MyNode2D"); + UndoRedo.CreateAction("Move the node"); + UndoRedo.AddDoMethod(this, nameof(DoSomething)); + UndoRedo.AddUndoMethod(this, nameof(UndoSomething)); + UndoRedo.AddDoProperty(node, "position", new Vector2(100, 100)); + UndoRedo.AddUndoProperty(node, "position", node.Position); + UndoRedo.CommitAction(); + } + [/csharp] + [/codeblocks] [method create_action], [method add_do_method], [method add_undo_method], [method add_do_property], [method add_undo_property], and [method commit_action] should be called one after the other, like in the example. Not doing so could lead to crashes. If you don't need to register a method, you can leave [method add_do_method] and [method add_undo_method] out; the same goes for properties. You can also register more than one method/property. </description> |