diff options
Diffstat (limited to 'doc/classes')
70 files changed, 491 insertions, 141 deletions
diff --git a/doc/classes/AStar2D.xml b/doc/classes/AStar2D.xml index a41da4c318..044e1206e9 100644 --- a/doc/classes/AStar2D.xml +++ b/doc/classes/AStar2D.xml @@ -278,7 +278,7 @@ <return type="void" /> <param index="0" name="num_nodes" type="int" /> <description> - Reserves space internally for [param num_nodes] points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity. + Reserves space internally for [param num_nodes] points. Useful if you're adding a known large number of points at once, such as points on a grid. The new capacity must be greater or equal to the old capacity. </description> </method> <method name="set_point_disabled"> diff --git a/doc/classes/AnimatedSprite2D.xml b/doc/classes/AnimatedSprite2D.xml index 88e543591a..cc1e9117f9 100644 --- a/doc/classes/AnimatedSprite2D.xml +++ b/doc/classes/AnimatedSprite2D.xml @@ -55,7 +55,7 @@ <param index="1" name="progress" type="float" /> <description> Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly. - [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]. + [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]: [codeblocks] [gdscript] var current_frame = animated_sprite.get_frame() diff --git a/doc/classes/AnimatedSprite3D.xml b/doc/classes/AnimatedSprite3D.xml index a466fc32ac..1b1f58e5f4 100644 --- a/doc/classes/AnimatedSprite3D.xml +++ b/doc/classes/AnimatedSprite3D.xml @@ -54,7 +54,7 @@ <param index="1" name="progress" type="float" /> <description> Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly. - [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]. + [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]: [codeblocks] [gdscript] var current_frame = animated_sprite.get_frame() diff --git a/doc/classes/Area2D.xml b/doc/classes/Area2D.xml index 4ad5db2b67..61a103f20d 100644 --- a/doc/classes/Area2D.xml +++ b/doc/classes/Area2D.xml @@ -132,7 +132,7 @@ <description> Emitted when a [Shape2D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer2D]. - [b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape2D] node from the shape index: [codeblocks] [gdscript] var other_shape_owner = area.shape_find_owner(area_shape_index) @@ -174,7 +174,7 @@ <description> Emitted when a [Shape2D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody2D] or a [TileMap]. [TileMap]s are detected if their [TileSet] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer2D]. - [b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape2D] node from the shape index: [codeblocks] [gdscript] var body_shape_owner = body.shape_find_owner(body_shape_index) diff --git a/doc/classes/Area3D.xml b/doc/classes/Area3D.xml index 8eedd3cdf2..aac98593ff 100644 --- a/doc/classes/Area3D.xml +++ b/doc/classes/Area3D.xml @@ -156,7 +156,7 @@ <description> Emitted when a [Shape3D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer3D]. - [b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape3D] node from the shape index: [codeblocks] [gdscript] var other_shape_owner = area.shape_find_owner(area_shape_index) @@ -198,7 +198,7 @@ <description> Emitted when a [Shape3D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody3D] or a [GridMap]. [GridMap]s are detected if their [MeshLibrary] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer3D]. - [b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape3D] node from the shape index: [codeblocks] [gdscript] var body_shape_owner = body.shape_find_owner(body_shape_index) diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml index 322d2ab9d4..59c1195b00 100644 --- a/doc/classes/Basis.xml +++ b/doc/classes/Basis.xml @@ -25,6 +25,7 @@ <return type="Basis" /> <description> Constructs a [Basis] identical to the [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Basis] with all of its components set to [constant Vector3.ZERO]. </description> </constructor> <constructor name="Basis"> @@ -303,7 +304,7 @@ <param index="1" name="weight" type="float" /> <description> Performs a spherical-linear interpolation with the [param to] basis, given a [param weight]. Both this basis and [param to] should represent a rotation. - [b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween]. + [b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween]: [codeblock] var start_basis = Basis.IDENTITY var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2) diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index c774667a7d..5b3f86c9f5 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -5,13 +5,13 @@ </brief_description> <description> [Button] is the standard themed button. It can contain text and an icon, and it will display them according to the current [Theme]. - [b]Example of creating a button and assigning an action when pressed by code:[/b] + [b]Example:[/b] Create a button and connect a method that will be called when the button is pressed: [codeblocks] [gdscript] func _ready(): var button = Button.new() button.text = "Click me" - button.pressed.connect(self._button_pressed) + button.pressed.connect(_button_pressed) add_child(button) func _button_pressed(): @@ -33,7 +33,7 @@ [/csharp] [/codeblocks] See also [BaseButton] which contains common properties and methods associated with this node. - [b]Note:[/b] Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions. + [b]Note:[/b] Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions. </description> <tutorials> <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/2712</link> diff --git a/doc/classes/CPUParticles2D.xml b/doc/classes/CPUParticles2D.xml index 99411c73aa..e8fa13fd0d 100644 --- a/doc/classes/CPUParticles2D.xml +++ b/doc/classes/CPUParticles2D.xml @@ -43,7 +43,7 @@ <return type="bool" /> <param index="0" name="particle_flag" type="int" enum="CPUParticles2D.ParticleFlags" /> <description> - Returns the enabled state of the given flag (see [enum ParticleFlags] for options). + Returns the enabled state of the given particle flag (see [enum ParticleFlags] for options). </description> </method> <method name="restart"> diff --git a/doc/classes/CallbackTweener.xml b/doc/classes/CallbackTweener.xml index afb9e70601..3a617d2a43 100644 --- a/doc/classes/CallbackTweener.xml +++ b/doc/classes/CallbackTweener.xml @@ -16,7 +16,7 @@ <param index="0" name="delay" type="float" /> <description> Makes the callback call delayed by given time in seconds. - [b]Example:[/b] Call [method Node.queue_free] after 2 seconds. + [b]Example:[/b] Call [method Node.queue_free] after 2 seconds: [codeblock] var tween = get_tree().create_tween() tween.tween_callback(queue_free).set_delay(2) diff --git a/doc/classes/CameraAttributes.xml b/doc/classes/CameraAttributes.xml index 1b1365eed4..cb5a7778de 100644 --- a/doc/classes/CameraAttributes.xml +++ b/doc/classes/CameraAttributes.xml @@ -25,7 +25,9 @@ Multiplier for the exposure amount. A higher value results in a brighter image. </member> <member name="exposure_sensitivity" type="float" setter="set_exposure_sensitivity" getter="get_exposure_sensitivity" default="100.0"> - Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. When [member auto_exposure_enabled] this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. + If [member auto_exposure_enabled] is [code]true[/code], this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + [b]Note:[/b] Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. </member> </members> </class> diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 78e9c392db..4e6535f3ca 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -333,7 +333,7 @@ <param index="9" name="orientation" type="int" enum="TextServer.Orientation" default="0" /> <description> Draws [param text] using the specified [param font] at the [param pos] (bottom-left corner using the baseline of the font). The text will have its color multiplied by [param modulate]. If [param width] 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] + [b]Example:[/b] Draw "Hello world", using the project's default font: [codeblocks] [gdscript] # If using this method in a script that redraws constantly, move the @@ -594,6 +594,7 @@ <members> <member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0"> Allows the current node to clip child nodes, essentially acting as a mask. + [b]Note:[/b] Clipping nodes cannot be nested or placed within [CanvasGroup]s. If an ancestor of this node clips its children or is a [CanvasGroup], then this node's clip mode should be set to [constant CLIP_CHILDREN_DISABLED] to avoid unexpected behavior. </member> <member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1"> The rendering layers in which this [CanvasItem] responds to [Light2D] nodes. diff --git a/doc/classes/CharFXTransform.xml b/doc/classes/CharFXTransform.xml index 403033f85d..28f5d38ee4 100644 --- a/doc/classes/CharFXTransform.xml +++ b/doc/classes/CharFXTransform.xml @@ -8,7 +8,6 @@ </description> <tutorials> <link title="BBCode in RichTextLabel">$DOCS_URL/tutorials/ui/bbcode_in_richtextlabel.html</link> - <link title="RichTextEffect test project (third-party)">https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link> </tutorials> <members> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)" keywords="colour"> diff --git a/doc/classes/CharacterBody2D.xml b/doc/classes/CharacterBody2D.xml index ede4d63cfc..30438be18b 100644 --- a/doc/classes/CharacterBody2D.xml +++ b/doc/classes/CharacterBody2D.xml @@ -69,7 +69,7 @@ <param index="0" name="slide_idx" type="int" /> <description> Returns a [KinematicCollision2D], which contains information about a collision that occurred during the last call to [method move_and_slide]. Since the body can collide several times in a single call to [method move_and_slide], you must specify the index of the collision in the range 0 to ([method get_slide_collision_count] - 1). - [b]Example usage:[/b] + [b]Example:[/b] Iterate through the collisions with a [code]for[/code] loop: [codeblocks] [gdscript] for i in get_slide_collision_count(): diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index 9fe42fff90..546d90fa3c 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -19,7 +19,7 @@ <return type="Color" /> <description> Constructs a default [Color] from opaque black. This is the same as [constant BLACK]. - [b]Note:[/b] in C#, constructs an empty color with all of its components set to [code]0.0[/code] (transparent black). + [b]Note:[/b] In C#, this constructs a [Color] with all of its components set to [code]0.0[/code] (transparent black). </description> </constructor> <constructor name="Color"> @@ -495,6 +495,15 @@ <member name="h" type="float" setter="" getter="" default="0.0"> The HSV hue of this color, on the range 0 to 1. </member> + <member name="ok_hsl_h" type="float" setter="" getter="" default="0.0"> + The OKHSL hue of this color, on the range 0 to 1. + </member> + <member name="ok_hsl_l" type="float" setter="" getter="" default="0.0"> + The OKHSL lightness of this color, on the range 0 to 1. + </member> + <member name="ok_hsl_s" type="float" setter="" getter="" default="0.0"> + The OKHSL saturation of this color, on the range 0 to 1. + </member> <member name="r" type="float" setter="" getter="" default="0.0"> The color's red component, typically on the range of 0 to 1. </member> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 0131f8f4af..80c5f8d96d 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -120,8 +120,8 @@ <return type="void" /> <param index="0" name="event" type="InputEvent" /> <description> - Virtual method to be implemented by the user. Use this method to process and accept inputs on UI elements. See [method accept_event]. - [b]Example usage for clicking a control:[/b] + Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also [method accept_event]. + [b]Example:[/b] Click on the control to print a message: [codeblocks] [gdscript] func _gui_input(event): @@ -142,13 +142,13 @@ } [/csharp] [/codeblocks] - The event won't trigger if: - * clicking outside the control (see [method _has_point]); - * control has [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; - * control is obstructed by another [Control] on top of it, which doesn't have [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; - * control's parent has [member mouse_filter] set to [constant MOUSE_FILTER_STOP] or has accepted the event; - * it happens outside the parent's rectangle and the parent has either [member clip_contents] enabled. - [b]Note:[/b] Event position is relative to the control origin. + If the [param event] inherits [InputEventMouse], this method will [b]not[/b] be called when: + - the control's [member mouse_filter] is set to [constant MOUSE_FILTER_IGNORE]; + - the control is obstructed by another control on top, that doesn't have [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; + - the control's parent has [member mouse_filter] set to [constant MOUSE_FILTER_STOP] or has accepted the event; + - the control's parent has [member clip_contents] enabled and the [param event]'s position is outside the parent's rectangle; + - the [param event]'s position is outside the control (see [method _has_point]). + [b]Note:[/b] The [param event]'s position is relative to this control's origin. </description> </method> <method name="_has_point" qualifiers="virtual const"> @@ -169,7 +169,7 @@ The returned node will be added as child to a [PopupPanel], so you should only provide the contents of that panel. That [PopupPanel] can be themed using [method Theme.set_stylebox] for the type [code]"TooltipPanel"[/code] (see [member tooltip_text] for an example). [b]Note:[/b] The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [member custom_minimum_size] to some non-zero value. [b]Note:[/b] The node (and any relevant children) should be [member CanvasItem.visible] when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. - [b]Example of usage with a custom-constructed node:[/b] + [b]Example:[/b] Use a constructed node as a tooltip: [codeblocks] [gdscript] func _make_custom_tooltip(for_text): @@ -186,7 +186,7 @@ } [/csharp] [/codeblocks] - [b]Example of usage with a custom scene instance:[/b] + [b]Example:[/b] Usa a scene instance as a tooltip: [codeblocks] [gdscript] func _make_custom_tooltip(for_text): @@ -228,7 +228,7 @@ <description> Creates a local override for a theme [Color] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_color_override]. See also [method get_theme_color]. - [b]Example of overriding a label's color and resetting it later:[/b] + [b]Example:[/b] Override a [Label]'s color and reset it later: [codeblocks] [gdscript] # Given the child Label node "MyLabel", override its font color with a custom value. @@ -292,10 +292,10 @@ <description> Creates a local override for a theme [StyleBox] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_stylebox_override]. See also [method get_theme_stylebox]. - [b]Example of modifying a property in a StyleBox by duplicating it:[/b] + [b]Example:[/b] Modify a property in a [StyleBox] by duplicating it: [codeblocks] [gdscript] - # The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + # The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. # Resources are shared across instances, so we need to duplicate it # to avoid modifying the appearance of all other buttons. var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate() @@ -306,7 +306,7 @@ $MyButton.remove_theme_stylebox_override("normal") [/gdscript] [csharp] - // The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + // The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. // Resources are shared across instances, so we need to duplicate it // to avoid modifying the appearance of all other buttons. StyleBoxFlat newStyleboxNormal = GetNode<Button>("MyButton").GetThemeStylebox("normal").Duplicate() as StyleBoxFlat; @@ -446,7 +446,7 @@ <description> Returns the position of this [Control] in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins. Equals to [member global_position] if the window is embedded (see [member Viewport.gui_embed_subwindows]). - [b]Example usage for showing a popup:[/b] + [b]Example:[/b] Show a popup at the mouse position: [codeblock] popup_menu.position = get_screen_position() + get_local_mouse_position() popup_menu.reset_size() @@ -809,9 +809,11 @@ <param index="1" name="can_drop_func" type="Callable" /> <param index="2" name="drop_func" type="Callable" /> <description> - Forwards the handling of this control's [method _get_drag_data], [method _can_drop_data] and [method _drop_data] virtual functions to delegate callables. - For each argument, if not empty, the delegate callable is used, otherwise the local (virtual) function is used. - The function format for each callable should be exactly the same as the virtual functions described above. + Sets the given callables to be used instead of the control's own drag-and-drop virtual methods. If a callable is empty, its respective virtual method is used as normal. + The arguments for each callable should be exactly the same as their respective virtual methods, which would be: + - [param drag_func] corresponds to [method _get_drag_data] and requires a [Vector2]; + - [param can_drop_func] corresponds to [method _can_drop_data] and requires both a [Vector2] and a [Variant]; + - [param drop_func] corresponds to [method _drop_data] and requires both a [Vector2] and a [Variant]. </description> </method> <method name="set_drag_preview"> diff --git a/doc/classes/Cubemap.xml b/doc/classes/Cubemap.xml index b7da3c4ec6..8a850920f7 100644 --- a/doc/classes/Cubemap.xml +++ b/doc/classes/Cubemap.xml @@ -6,8 +6,27 @@ <description> A cubemap is made of 6 textures organized in layers. They are typically used for faking reflections in 3D rendering (see [ReflectionProbe]). It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods. This resource is typically used as a uniform in custom shaders. Few core Godot methods make use of [Cubemap] resources. - To create such a texture file yourself, reimport your image files using the Godot Editor import presets. - [b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map. + To create such a texture file yourself, reimport your image files using the Godot Editor import presets. The expected image order is X+, X-, Y+, Y-, Z+, Z- (in Godot's coordinate system, so Y+ is "up" and Z- is "forward"). You can use one of the following templates as a base: + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_2x3.webp]2×3 cubemap template (default layout option)[/url] + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_3x2.webp]3×2 cubemap template[/url] + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_1x6.webp]1×6 cubemap template[/url] + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_6x1.webp]6×1 cubemap template[/url] + [b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. To use a cubemap as a skybox, convert the default [PanoramaSkyMaterial] to a [ShaderMaterial] using the [b]Convert to ShaderMaterial[/b] resource dropdown option, then replace its code with the following: + [codeblock lang=text] + shader_type sky; + + uniform samplerCube source_panorama : filter_linear, source_color, hint_default_black; + uniform float exposure : hint_range(0, 128) = 1.0; + + void sky() { + // If importing a cubemap from another engine, you may need to flip one of the `EYEDIR` components below + // by replacing it with `-EYEDIR`. + vec3 eyedir = vec3(EYEDIR.x, EYEDIR.y, EYEDIR.z); + COLOR = texture(source_panorama, eyedir).rgb * exposure; + } + [/codeblock] + After replacing the shader code and saving, specify the imported Cubemap resource in the Shader Parameters section of the ShaderMaterial in the inspector. + Alternatively, you can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map and use [PanoramaSkyMaterial] as usual. </description> <tutorials> </tutorials> diff --git a/doc/classes/DirAccess.xml b/doc/classes/DirAccess.xml index 9c71addf0c..dcd2d527e2 100644 --- a/doc/classes/DirAccess.xml +++ b/doc/classes/DirAccess.xml @@ -60,6 +60,7 @@ } [/csharp] [/codeblocks] + Keep in mind that file names may change or be remapped after export. If you want to see the actual resource file list as it appears in the editor, use [method ResourceLoader.list_directory] instead. </description> <tutorials> <link title="File system">$DOCS_URL/tutorials/scripting/filesystem.html</link> diff --git a/doc/classes/EditorExportPlugin.xml b/doc/classes/EditorExportPlugin.xml index dc1cd89642..23e3f4139c 100644 --- a/doc/classes/EditorExportPlugin.xml +++ b/doc/classes/EditorExportPlugin.xml @@ -35,9 +35,16 @@ <param index="0" name="resource" type="Resource" /> <param index="1" name="path" type="String" /> <description> - Customize a resource. If changes are made to it, return the same or a new resource. Otherwise, return [code]null[/code]. - The [i]path[/i] argument is only used when customizing an actual file, otherwise this means that this resource is part of another one and it will be empty. + Customize a resource. If changes are made to it, return the same or a new resource. Otherwise, return [code]null[/code]. When a new resource is returned, [param resource] will be replaced by a copy of the new resource. + The [param path] argument is only used when customizing an actual file, otherwise this means that this resource is part of another one and it will be empty. Implementing this method is required if [method _begin_customize_resources] returns [code]true[/code]. + [b]Note:[/b] When customizing any of the following types and returning another resource, the other resource should not be skipped using [method skip] in [method _export_file]: + - [AtlasTexture] + - [CompressedCubemap] + - [CompressedCubemapArray] + - [CompressedTexture2D] + - [CompressedTexture2DArray] + - [CompressedTexture3D] </description> </method> <method name="_customize_scene" qualifiers="virtual"> diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml index e5f3010366..186f249281 100644 --- a/doc/classes/EditorImportPlugin.xml +++ b/doc/classes/EditorImportPlugin.xml @@ -154,7 +154,7 @@ <param index="1" name="option_name" type="StringName" /> <param index="2" name="options" type="Dictionary" /> <description> - This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. For example: + This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. [codeblocks] [gdscript] func _get_option_visibility(option, options): diff --git a/doc/classes/EditorInterface.xml b/doc/classes/EditorInterface.xml index 43059db8b2..0304499a61 100644 --- a/doc/classes/EditorInterface.xml +++ b/doc/classes/EditorInterface.xml @@ -301,6 +301,15 @@ See also [method Window.set_unparent_when_invisible]. </description> </method> + <method name="popup_method_selector"> + <return type="void" /> + <param index="0" name="object" type="Object" /> + <param index="1" name="callback" type="Callable" /> + <param index="2" name="current_value" type="String" default="""" /> + <description> + Pops up an editor dialog for selecting a method from [param object]. The [param callback] must take a single argument of type [String] which will contain the name of the selected method or be empty if the dialog is canceled. If [param current_value] is provided, the method will be selected automatically in the method list, if it exists. + </description> + </method> <method name="popup_node_selector"> <return type="void" /> <param index="0" name="callback" type="Callable" /> diff --git a/doc/classes/EditorProperty.xml b/doc/classes/EditorProperty.xml index 2b1083393f..4ff541f72d 100644 --- a/doc/classes/EditorProperty.xml +++ b/doc/classes/EditorProperty.xml @@ -132,6 +132,13 @@ Emitted when a property was deleted. Used internally. </description> </signal> + <signal name="property_favorited"> + <param index="0" name="property" type="StringName" /> + <param index="1" name="favorited" type="bool" /> + <description> + Emit it if you want to mark a property as favorited, making it appear at the top of the inspector. + </description> + </signal> <signal name="property_keyed"> <param index="0" name="property" type="StringName" /> <description> diff --git a/doc/classes/EditorResourcePreviewGenerator.xml b/doc/classes/EditorResourcePreviewGenerator.xml index 9c9b6d11b2..89bfe836d7 100644 --- a/doc/classes/EditorResourcePreviewGenerator.xml +++ b/doc/classes/EditorResourcePreviewGenerator.xml @@ -4,7 +4,7 @@ Custom generator of previews. </brief_description> <description> - Custom code to generate previews. Please check [code]file_dialog/thumbnail_size[/code] in [EditorSettings] to find out the right size to do previews at. + Custom code to generate previews. Check [member EditorSettings.filesystem/file_dialog/thumbnail_size] to find a proper size to generate previews at. </description> <tutorials> </tutorials> diff --git a/doc/classes/EditorScenePostImport.xml b/doc/classes/EditorScenePostImport.xml index 7325d31fc5..f8938c459c 100644 --- a/doc/classes/EditorScenePostImport.xml +++ b/doc/classes/EditorScenePostImport.xml @@ -5,7 +5,7 @@ </brief_description> <description> Imported scenes can be automatically modified right after import by setting their [b]Custom Script[/b] Import property to a [code]tool[/code] script that inherits from this class. - The [method _post_import] callback receives the imported scene's root node and returns the modified version of the scene. Usage example: + The [method _post_import] callback receives the imported scene's root node and returns the modified version of the scene: [codeblocks] [gdscript] @tool # Needed so it runs in editor. diff --git a/doc/classes/EditorScript.xml b/doc/classes/EditorScript.xml index bd18852dbc..e342966fe8 100644 --- a/doc/classes/EditorScript.xml +++ b/doc/classes/EditorScript.xml @@ -6,7 +6,7 @@ <description> Scripts extending this class and implementing its [method _run] method can be executed from the Script Editor's [b]File > Run[/b] menu option (or by pressing [kbd]Ctrl + Shift + X[/kbd]) while the editor is running. This is useful for adding custom in-editor functionality to Godot. For more complex additions, consider using [EditorPlugin]s instead. [b]Note:[/b] Extending scripts need to have [code]tool[/code] mode enabled. - [b]Example script:[/b] + [b]Example:[/b] Running the following script prints "Hello from the Godot Editor!": [codeblocks] [gdscript] @tool diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index ea5207e826..15b03ddbd8 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -1061,7 +1061,7 @@ Determines whether online features are enabled in the editor, such as the Asset Library or update checks. Disabling these online features helps alleviate privacy concerns by preventing the editor from making HTTP requests to the Godot website or third-party platforms hosting assets from the Asset Library. </member> <member name="network/debug/remote_host" type="String" setter="" getter=""> - The address to listen to when starting the remote debugger. This can be set to [code]0.0.0.0[/code] to allow external clients to connect to the remote debugger (instead of restricting the remote debugger to connections from [code]localhost[/code]). + The address to listen to when starting the remote debugger. This can be set to this device's local IP address to allow external clients to connect to the remote debugger (instead of restricting the remote debugger to connections from [code]localhost[/code]). </member> <member name="network/debug/remote_port" type="int" setter="" getter=""> The port to listen to when starting the remote debugger. Godot will try to use port numbers above the configured number if the configured number is already taken by another application. @@ -1091,9 +1091,11 @@ </member> <member name="run/bottom_panel/action_on_play" type="int" setter="" getter=""> The action to execute on the bottom panel when running the project. + [b]Note:[/b] This option won't do anything if the bottom panel switching is locked using the pin button in the corner of the bottom panel. </member> <member name="run/bottom_panel/action_on_stop" type="int" setter="" getter=""> The action to execute on the bottom panel when stopping the project. + [b]Note:[/b] This option won't do anything if the bottom panel switching is locked using the pin button in the corner of the bottom panel. </member> <member name="run/output/always_clear_output_on_play" type="bool" setter="" getter=""> If [code]true[/code], the editor will clear the Output panel when running the project. @@ -1326,6 +1328,9 @@ <member name="text_editor/script_list/group_help_pages" type="bool" setter="" getter=""> If [code]true[/code], class reference pages are grouped together at the bottom of the Script Editor's script list. </member> + <member name="text_editor/script_list/highlight_scene_scripts" type="bool" setter="" getter=""> + If [code]true[/code], the scripts that are used by the current scene are highlighted in the Script Editor's script list. + </member> <member name="text_editor/script_list/list_script_names_as" type="int" setter="" getter=""> Specifies how script paths should be displayed in Script Editor's script list. If using the "Name" option and some scripts share the same file name, more parts of their paths are revealed to avoid conflicts. </member> diff --git a/doc/classes/EditorTranslationParserPlugin.xml b/doc/classes/EditorTranslationParserPlugin.xml index a47a41594e..43bbeaefa7 100644 --- a/doc/classes/EditorTranslationParserPlugin.xml +++ b/doc/classes/EditorTranslationParserPlugin.xml @@ -69,8 +69,7 @@ msgidsContextPlural.Add(new Godot.Collections.Array{"Only with context", "a friendly context", ""}); [/csharp] [/codeblocks] - [b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [FileAccess] type. - For example: + [b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [FileAccess] type. For example: [codeblocks] [gdscript] func _parse_file(path, msgids, msgids_context_plural): diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index 1779408a4d..47fc48305b 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -182,7 +182,8 @@ [b]Note:[/b] [member glow_map] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_map_strength" type="float" setter="set_glow_map_strength" getter="get_glow_map_strength" default="0.8"> - How strong of an impact the [member glow_map] should have on the overall glow effect. A strength of [code]0.0[/code] means the glow map has no effect on the overall glow effect. A strength of [code]1.0[/code] means the glow has a full effect on the overall glow effect (and can turn off glow entirely in specific areas of the screen if the glow map has black areas). + How strong of an influence the [member glow_map] should have on the overall glow effect. A strength of [code]0.0[/code] means the glow map has no influence, while a strength of [code]1.0[/code] means the glow map has full influence. + [b]Note:[/b] If the glow map has black areas, a value of [code]1.0[/code] can also turn off the glow effect entirely in specific areas of the screen. [b]Note:[/b] [member glow_map_strength] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_mix" type="float" setter="set_glow_mix" getter="get_glow_mix" default="0.05"> diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index 5888e30339..b782937a8a 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -34,7 +34,7 @@ [/codeblocks] In the example above, the file will be saved in the user data folder as specified in the [url=$DOCS_URL/tutorials/io/data_paths.html]Data paths[/url] documentation. [FileAccess] will close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code]. [method close] can be used to close it before then explicitly. In C# the reference must be disposed manually, which can be done with the [code]using[/code] statement or by calling the [code]Dispose[/code] method directly. - [b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of [FileAccess], as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. + [b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of [FileAccess], as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. If using [FileAccess], make sure the file is included in the export by changing its import mode to [b]Keep File (exported as is)[/b] in the Import dock, or, for files where this option is not available, change the non-resource export filter in the Export dialog to include the file's extension (e.g. [code]*.txt[/code]). [b]Note:[/b] Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing [b]Alt + F4[/b]). If you stop the project execution by pressing [b]F8[/b] while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling [method flush] at regular intervals. </description> <tutorials> diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml index 3c48f5ba31..96232f4277 100644 --- a/doc/classes/GPUParticles2D.xml +++ b/doc/classes/GPUParticles2D.xml @@ -136,7 +136,7 @@ <signal name="finished"> <description> Emitted when all active particles have finished processing. To immediately restart the emission cycle, call [method restart]. - Never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. + This signal is never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. [b]Note:[/b] For [member one_shot] emitters, due to the particles being computed on the GPU, there may be a short period after receiving the signal during which setting [member emitting] to [code]true[/code] will not restart the emission cycle. This delay is avoided by instead calling [method restart]. </description> </signal> diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index 61a3b467f1..f5df857391 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -160,8 +160,8 @@ <signals> <signal name="finished"> <description> - Emitted when all active particles have finished processing. To immediately emit new particles, call [method restart]. - Never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. + Emitted when all active particles have finished processing. To immediately restart the emission cycle, call [method restart]. + This signal is never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. [b]Note:[/b] For [member one_shot] emitters, due to the particles being computed on the GPU, there may be a short period after receiving the signal during which setting [member emitting] to [code]true[/code] will not restart the emission cycle. This delay is avoided by instead calling [method restart]. </description> </signal> diff --git a/doc/classes/GPUParticlesCollision3D.xml b/doc/classes/GPUParticlesCollision3D.xml index 089747b7ee..2d398edd5e 100644 --- a/doc/classes/GPUParticlesCollision3D.xml +++ b/doc/classes/GPUParticlesCollision3D.xml @@ -16,8 +16,8 @@ <members> <member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="4294967295"> The particle rendering layers ([member VisualInstance3D.layers]) that will be affected by the collision shape. By default, all particles that have [member ParticleProcessMaterial.collision_mode] set to [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT] will be affected by a collision shape. - After configuring particle nodes accordingly, specific layers can be unchecked to prevent certain particles from being affected by attractors. For example, this can be used if you're using an attractor as part of a spell effect but don't want the attractor to affect unrelated weather particles at the same position. - Particle attraction can also be disabled on a per-process material basis by setting [member ParticleProcessMaterial.attractor_interaction_enabled] on the [GPUParticles3D] node. + After configuring particle nodes accordingly, specific layers can be unchecked to prevent certain particles from being affected by colliders. For example, this can be used if you're using a collider as part of a spell effect but don't want the collider to affect unrelated weather particles at the same position. + Particle collision can also be disabled on a per-process material basis by setting [member ParticleProcessMaterial.collision_mode] on the [GPUParticles3D] node. </member> </members> </class> diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index af98636056..366038e43f 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -277,7 +277,11 @@ HTTP status code [code]102 Processing[/code] (WebDAV). Indicates that the server has received and is processing the request, but no response is available yet. </constant> <constant name="RESPONSE_OK" value="200" enum="ResponseCode"> - HTTP status code [code]200 OK[/code]. The request has succeeded. Default response for successful requests. Meaning varies depending on the request. GET: The resource has been fetched and is transmitted in the message body. HEAD: The entity headers are in the message body. POST: The resource describing the result of the action is transmitted in the message body. TRACE: The message body contains the request message as received by the server. + HTTP status code [code]200 OK[/code]. The request has succeeded. Default response for successful requests. Meaning varies depending on the request: + - [constant METHOD_GET]: The resource has been fetched and is transmitted in the message body. + - [constant METHOD_HEAD]: The entity headers are in the message body. + - [constant METHOD_POST]: The resource describing the result of the action is transmitted in the message body. + - [constant METHOD_TRACE]: The message body contains the request message as received by the server. </constant> <constant name="RESPONSE_CREATED" value="201" enum="ResponseCode"> HTTP status code [code]201 Created[/code]. The request has succeeded and a new resource has been created as a result of it. This is typically the response sent after a PUT request. diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index a4adf4d1b1..36f5e82652 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -8,7 +8,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP. [b]Warning:[/b] See the notes and warnings on [HTTPClient] for limitations, especially regarding TLS security. [b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. - [b]Example of contacting a REST API and printing one of its returned fields:[/b] + [b]Example:[/b] Contact a REST API and print one of its returned fields: [codeblocks] [gdscript] func _ready(): @@ -80,7 +80,7 @@ } [/csharp] [/codeblocks] - [b]Example of loading and displaying an image using HTTPRequest:[/b] + [b]Example:[/b] Load an image using [HTTPRequest] and display it: [codeblocks] [gdscript] func _ready(): @@ -150,7 +150,7 @@ } [/csharp] [/codeblocks] - [b]Gzipped response bodies[/b]: HTTPRequest will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. + [b]Note:[/b] [HTTPRequest] nodes will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. </description> <tutorials> <link title="Making HTTP requests">$DOCS_URL/tutorials/networking/http_request_class.html</link> diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 9b71a8c37f..4421318be7 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -48,6 +48,7 @@ <param index="2" name="dst" type="Vector2i" /> <description> Copies [param src_rect] from [param src] image to this image at coordinates [param dst], clipped accordingly to both image bounds. This image and [param src] image [b]must[/b] have the same format. [param src_rect] with non-positive size is treated as empty. + [b]Note:[/b] The alpha channel data in [param src] will overwrite the corresponding data in this image at the target position. To blend alpha channels, use [method blend_rect] instead. </description> </method> <method name="blit_rect_mask"> diff --git a/doc/classes/LookAtModifier3D.xml b/doc/classes/LookAtModifier3D.xml new file mode 100644 index 0000000000..e85da06c3a --- /dev/null +++ b/doc/classes/LookAtModifier3D.xml @@ -0,0 +1,156 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="LookAtModifier3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + The [SkeletonModifier3D] rotates a bone to look a target. + </brief_description> + <description> + This [SkeletonModifier3D] rotates a bone to look a target. This is helpful for moving character's head to look at the player, rotating a turret to look at a target, or any other case where you want to make a bone rotate towards something quickly and easily. + When applying multiple [LookAtModifier3D]s, the [LookAtModifier3D] assigned to the parent bone must be put above the [LookAtModifier3D] assigned to the child bone in the list in order for the child bone results to be correct. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_interpolation_remaining" qualifiers="const"> + <return type="float" /> + <description> + Returns the remaining seconds of the time-based interpolation. + </description> + </method> + <method name="is_interpolating" qualifiers="const"> + <return type="bool" /> + <description> + Returns whether the time-based interpolation is running or not. If [code]true[/code], it is equivalent to [method get_interpolation_remaining] being [code]0[/code]. + This is useful to determine whether a [LookAtModifier3D] can be removed safely. + </description> + </method> + <method name="is_target_within_limitation" qualifiers="const"> + <return type="bool" /> + <description> + Returns whether the target is within the angle limitations. It is useful for unsetting the [member target_node] when the target is outside of the angle limitations. + [b]Note:[/b] The value is updated after [method SkeletonModifier3D._process_modification]. To retrieve this value correctly, we recommend using the signal [signal SkeletonModifier3D.modification_processed]. + </description> + </method> + </methods> + <members> + <member name="bone" type="int" setter="set_bone" getter="get_bone" default="0"> + The bone index of the [Skeleton3D] that the modification will operate on. + </member> + <member name="duration" type="float" setter="set_duration" getter="get_duration" default="0.0"> + The duration of the time-based interpolation. Interpolation is triggered at the following cases: + - When the target node is changed + - When an axis is flipped due to angle limitation + [b]Note:[/b] The flipping occurs when the target is outside the angle limitation and the internally computed secondary rotation axis of the forward vector is flipped. Visually, it occurs when the target is outside the angle limitation and crosses the plane of the [member forward_axis] and [member primary_rotation_axis]. + </member> + <member name="ease_type" type="int" setter="set_ease_type" getter="get_ease_type" enum="Tween.EaseType" default="0"> + The ease type of the time-based interpolation. See also [enum Tween.EaseType]. + </member> + <member name="forward_axis" type="int" setter="set_forward_axis" getter="get_forward_axis" enum="LookAtModifier3D.BoneAxis" default="4"> + The forward axis of the bone. This [SkeletonModifier3D] modifies the bone so that this axis points toward the [member target_node]. + </member> + <member name="origin_bone" type="int" setter="set_origin_bone" getter="get_origin_bone"> + If [member origin_from] is [constant ORIGIN_FROM_SPECIFIC_BONE], the bone global pose position specified for this is used as origin. + </member> + <member name="origin_external_node" type="NodePath" setter="set_origin_external_node" getter="get_origin_external_node"> + If [member origin_from] is [constant ORIGIN_FROM_EXTERNAL_NODE], the global position of the [Node3D] specified for this is used as origin. + </member> + <member name="origin_from" type="int" setter="set_origin_from" getter="get_origin_from" enum="LookAtModifier3D.OriginFrom" default="0"> + This value determines from what origin is retrieved for use in the calculation of the forward vector. + </member> + <member name="origin_offset" type="Vector3" setter="set_origin_offset" getter="get_origin_offset" default="Vector3(0, 0, 0)"> + The offset of the bone pose origin. Matching the origins by offset is useful for cases where multiple bones must always face the same direction, such as the eyes. + [b]Note:[/b] This value indicates the local position of the object set in [member origin_from]. + </member> + <member name="origin_safe_margin" type="float" setter="set_origin_safe_margin" getter="get_origin_safe_margin" default="0.1"> + If the target passes through too close to the origin than this value, time-based interpolation is used even if the target is within the angular limitations, to prevent the angular velocity from becoming too high. + </member> + <member name="primary_damp_threshold" type="float" setter="set_primary_damp_threshold" getter="get_primary_damp_threshold"> + The threshold to start damping for [member primary_limit_angle]. It provides non-linear (b-spline) interpolation, let it feel more resistance the more it rotate to the edge limit. This is useful for simulating the limits of human motion. + If [code]1.0[/code], no damping is performed. If [code]0.0[/code], damping is always performed. + </member> + <member name="primary_limit_angle" type="float" setter="set_primary_limit_angle" getter="get_primary_limit_angle"> + The limit angle of the primary rotation when [member symmetry_limitation] is [code]true[/code]. + </member> + <member name="primary_negative_damp_threshold" type="float" setter="set_primary_negative_damp_threshold" getter="get_primary_negative_damp_threshold"> + The threshold to start damping for [member primary_negative_limit_angle]. + </member> + <member name="primary_negative_limit_angle" type="float" setter="set_primary_negative_limit_angle" getter="get_primary_negative_limit_angle"> + The limit angle of negative side of the primary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="primary_positive_damp_threshold" type="float" setter="set_primary_positive_damp_threshold" getter="get_primary_positive_damp_threshold"> + The threshold to start damping for [member primary_positive_limit_angle]. + </member> + <member name="primary_positive_limit_angle" type="float" setter="set_primary_positive_limit_angle" getter="get_primary_positive_limit_angle"> + The limit angle of positive side of the primary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="primary_rotation_axis" type="int" setter="set_primary_rotation_axis" getter="get_primary_rotation_axis" enum="Vector3.Axis" default="1"> + The axis of the first rotation. This [SkeletonModifier3D] works by compositing the rotation by Euler angles to prevent to rotate the [member forward_axis]. + </member> + <member name="secondary_damp_threshold" type="float" setter="set_secondary_damp_threshold" getter="get_secondary_damp_threshold"> + The threshold to start damping for [member secondary_limit_angle]. + </member> + <member name="secondary_limit_angle" type="float" setter="set_secondary_limit_angle" getter="get_secondary_limit_angle"> + The limit angle of the secondary rotation when [member symmetry_limitation] is [code]true[/code]. + </member> + <member name="secondary_negative_damp_threshold" type="float" setter="set_secondary_negative_damp_threshold" getter="get_secondary_negative_damp_threshold"> + The threshold to start damping for [member secondary_negative_limit_angle]. + </member> + <member name="secondary_negative_limit_angle" type="float" setter="set_secondary_negative_limit_angle" getter="get_secondary_negative_limit_angle"> + The limit angle of negative side of the secondary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="secondary_positive_damp_threshold" type="float" setter="set_secondary_positive_damp_threshold" getter="get_secondary_positive_damp_threshold"> + The threshold to start damping for [member secondary_positive_limit_angle]. + </member> + <member name="secondary_positive_limit_angle" type="float" setter="set_secondary_positive_limit_angle" getter="get_secondary_positive_limit_angle"> + The limit angle of positive side of the secondary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="symmetry_limitation" type="bool" setter="set_symmetry_limitation" getter="is_limitation_symmetry"> + If [code]true[/code], the limitations are spread from the bone symmetrically. + If [code]false[/code], the limitation can be specified separately for each side of the bone rest. + </member> + <member name="target_node" type="NodePath" setter="set_target_node" getter="get_target_node" default="NodePath("")"> + The [NodePath] to the node that is the target for the look at modification. This node is what the modification will rotate the bone to. + </member> + <member name="transition_type" type="int" setter="set_transition_type" getter="get_transition_type" enum="Tween.TransitionType" default="0"> + The transition type of the time-based interpolation. See also [enum Tween.TransitionType]. + </member> + <member name="use_angle_limitation" type="bool" setter="set_use_angle_limitation" getter="is_using_angle_limitation" default="false"> + If [code]true[/code], limits the degree of rotation. This helps prevent the character's neck from rotating 360 degrees. + [b]Note:[/b] As with [AnimationTree] blending, interpolation is provided that favors [method Skeleton3D.get_bone_rest]. This means that interpolation does not select the shortest path in some cases. + [b]Note:[/b] Some [member transition_type] may exceed the limitations (e.g. `Back`, `Elastic`, and `Spring`). If interpolation occurs while overshooting the limitations, the result might possibly not respect the bone rest. + </member> + <member name="use_secondary_rotation" type="bool" setter="set_use_secondary_rotation" getter="is_using_secondary_rotation" default="true"> + If [code]true[/code], provides rotation by two axes. + </member> + </members> + <constants> + <constant name="BONE_AXIS_PLUS_X" value="0" enum="BoneAxis"> + Enumerated value for the +X axis. + </constant> + <constant name="BONE_AXIS_MINUS_X" value="1" enum="BoneAxis"> + Enumerated value for the -X axis. + </constant> + <constant name="BONE_AXIS_PLUS_Y" value="2" enum="BoneAxis"> + Enumerated value for the +Y axis. + </constant> + <constant name="BONE_AXIS_MINUS_Y" value="3" enum="BoneAxis"> + Enumerated value for the -Y axis. + </constant> + <constant name="BONE_AXIS_PLUS_Z" value="4" enum="BoneAxis"> + Enumerated value for the +Z axis. + </constant> + <constant name="BONE_AXIS_MINUS_Z" value="5" enum="BoneAxis"> + Enumerated value for the -Z axis. + </constant> + <constant name="ORIGIN_FROM_SELF" value="0" enum="OriginFrom"> + The bone rest position of the bone specified in [member bone] is used as origin. + </constant> + <constant name="ORIGIN_FROM_SPECIFIC_BONE" value="1" enum="OriginFrom"> + The bone global pose position of the bone specified in [member origin_bone] is used as origin. + [b]Note:[/b] It is recommended that you select only the parent bone unless you are familiar with the bone processing process. The specified bone pose at the time the [LookAtModifier3D] is processed is used as a reference. In other words, if you specify a child bone and the [LookAtModifier3D] causes the child bone to move, the rendered result and direction will not match. + </constant> + <constant name="ORIGIN_FROM_EXTERNAL_NODE" value="2" enum="OriginFrom"> + The global position of the [Node3D] specified in [member origin_external_node] is used as origin. + [b]Note:[/b] Same as [constant ORIGIN_FROM_SPECIFIC_BONE], when specifying a [BoneAttachment3D] with a child bone assigned, the rendered result and direction will not match. + </constant> + </constants> +</class> diff --git a/doc/classes/MeshInstance3D.xml b/doc/classes/MeshInstance3D.xml index d8e2c43566..a0a773b90a 100644 --- a/doc/classes/MeshInstance3D.xml +++ b/doc/classes/MeshInstance3D.xml @@ -120,7 +120,7 @@ <param index="1" name="material" type="Material" /> <description> Sets the override [param material] for the specified [param surface] of the [Mesh] resource. This material is associated with this [MeshInstance3D] rather than with [member mesh]. - [b]Note:[/b] This assigns the [Material] associated to the [MeshInstance3D]'s Surface Material Override properties, not the material within the [Mesh] resource. To set the material within the [Mesh] resource, use [method Mesh.surface_get_material] instead. + [b]Note:[/b] This assigns the [Material] associated to the [MeshInstance3D]'s Surface Material Override properties, not the material within the [Mesh] resource. To set the material within the [Mesh] resource, use [method Mesh.surface_set_material] instead. </description> </method> </methods> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index c07948b546..3cb76e2926 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -1006,8 +1006,8 @@ [b]Note:[/b] When changing the name, the following characters will be replaced with an underscore: ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code] [code]%[/code]). In particular, the [code]@[/code] character is reserved for auto-generated names. See also [method String.validate_node_name]. </member> <member name="owner" type="Node" setter="set_owner" getter="get_owner"> - The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a [PackedScene], all the nodes it owns are also saved with it. - [b]Note:[/b] In the editor, nodes not owned by the scene root are usually not displayed in the Scene dock, and will [b]not[/b] be saved. To prevent this, remember to set the owner after calling [method add_child]. See also (see [member unique_name_in_owner]) + The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a [PackedScene], all the nodes it owns are also saved with it. See also [member unique_name_in_owner]. + [b]Note:[/b] In the editor, nodes not owned by the scene root are usually not displayed in the Scene dock, and will [b]not[/b] be saved. To prevent this, remember to set the owner after calling [method add_child]. </member> <member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" enum="Node.PhysicsInterpolationMode" default="0"> Allows enabling or disabling physics interpolation per node, offering a finer grain of control than turning physics interpolation on and off globally. See [member ProjectSettings.physics/common/physics_interpolation] and [member SceneTree.physics_interpolation] for the global setting. diff --git a/doc/classes/NodePath.xml b/doc/classes/NodePath.xml index d0ec81ab45..628c7106f2 100644 --- a/doc/classes/NodePath.xml +++ b/doc/classes/NodePath.xml @@ -57,7 +57,7 @@ <description> Constructs a [NodePath] from a [String]. The created path is absolute if prefixed with a slash (see [method is_absolute]). The "subnames" optionally included after the path to the target node can point to properties, and can also be nested. - Examples of strings that could be node paths: + The following strings can be valid node paths: [codeblock] # Points to the Sprite2D node. "Level/RigidBody2D/Sprite2D" diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 777950c075..49350597f5 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -53,7 +53,7 @@ Creates a new process that runs independently of Godot. It will not terminate when Godot terminates. The path specified in [param path] must exist and be an executable file or macOS [code].app[/code] bundle. The path is resolved based on the current platform. The [param arguments] are used in the given order and separated by a space. On Windows, if [param open_console] is [code]true[/code] and the process is a console app, a new terminal window will be opened. If the process is successfully created, this method returns its process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). Otherwise, this method returns [code]-1[/code]. - For example, running another instance of the project: + [b]Example:[/b] Run another instance of the project: [codeblocks] [gdscript] var pid = OS.create_process(OS.get_executable_path(), []) @@ -184,7 +184,7 @@ Command-line arguments can be written in any form, including both [code]--key value[/code] and [code]--key=value[/code] forms so they can be properly parsed, as long as custom command-line arguments do not conflict with engine arguments. You can also incorporate environment variables using the [method get_environment] method. You can set [member ProjectSettings.editor/run/main_run_args] to define command-line arguments to be passed by the editor when running the project. - Here's a minimal example on how to parse command-line arguments into a [Dictionary] using the [code]--key=value[/code] form for arguments: + [b]Example:[/b] Parse command-line arguments into a [Dictionary] using the [code]--key=value[/code] form for arguments: [codeblocks] [gdscript] var arguments = {} @@ -356,7 +356,7 @@ <return type="String" /> <description> Returns the model name of the current device. - [b]Note:[/b] This method is implemented on Android and iOS. Returns [code]"GenericDevice"[/code] on unsupported platforms. + [b]Note:[/b] This method is implemented on Android, iOS, macOS, and Windows. Returns [code]"GenericDevice"[/code] on unsupported platforms. </description> </method> <method name="get_name" qualifiers="const"> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index a130a71826..81f666dd16 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -854,7 +854,7 @@ <param index="0" name="signal" type="StringName" /> <description> Returns [code]true[/code] if the given [param signal] name exists in the object. - [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="has_user_signal" qualifiers="const"> @@ -898,7 +898,7 @@ <param index="1" name="callable" type="Callable" /> <description> Returns [code]true[/code] if a connection exists between the given [param signal] name and [param callable]. - [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="is_queued_for_deletion" qualifiers="const"> diff --git a/doc/classes/PCKPacker.xml b/doc/classes/PCKPacker.xml index ec0300c068..f8f7dbee01 100644 --- a/doc/classes/PCKPacker.xml +++ b/doc/classes/PCKPacker.xml @@ -26,11 +26,18 @@ <methods> <method name="add_file"> <return type="int" enum="Error" /> - <param index="0" name="pck_path" type="String" /> + <param index="0" name="target_path" type="String" /> <param index="1" name="source_path" type="String" /> <param index="2" name="encrypt" type="bool" default="false" /> <description> - Adds the [param source_path] file to the current PCK package at the [param pck_path] internal path (should start with [code]res://[/code]). + Adds the [param source_path] file to the current PCK package at the [param target_path] internal path. The [code]res://[/code] prefix for [param target_path] is optional and stripped internally. + </description> + </method> + <method name="add_file_removal"> + <return type="int" enum="Error" /> + <param index="0" name="target_path" type="String" /> + <description> + Registers a file removal of the [param target_path] internal path to the PCK. This is mainly used for patches. If the file at this path has been loaded from a previous PCK, it will be removed. The [code]res://[/code] prefix for [param target_path] is optional and stripped internally. </description> </method> <method name="flush"> diff --git a/doc/classes/PackedScene.xml b/doc/classes/PackedScene.xml index 415e468e21..baff5fed57 100644 --- a/doc/classes/PackedScene.xml +++ b/doc/classes/PackedScene.xml @@ -7,7 +7,7 @@ A simplified interface to a scene file. Provides access to operations and checks that can be performed on the scene resource itself. Can be used to save a node to a file. When saving, the node as well as all the nodes it owns get saved (see [member Node.owner] property). [b]Note:[/b] The node doesn't need to own itself. - [b]Example of loading a saved scene:[/b] + [b]Example:[/b] Load a saved scene: [codeblocks] [gdscript] # Use load() instead of preload() if the path isn't known at compile-time. @@ -22,7 +22,7 @@ AddChild(scene); [/csharp] [/codeblocks] - [b]Example of saving a node with different owners:[/b] The following example creates 3 objects: [Node2D] ([code]node[/code]), [RigidBody2D] ([code]body[/code]) and [CollisionObject2D] ([code]collision[/code]). [code]collision[/code] is a child of [code]body[/code] which is a child of [code]node[/code]. Only [code]body[/code] is owned by [code]node[/code] and [method pack] will therefore only save those two nodes, but not [code]collision[/code]. + [b]Example:[/b] Save a node with different owners. The following example creates 3 objects: [Node2D] ([code]node[/code]), [RigidBody2D] ([code]body[/code]) and [CollisionObject2D] ([code]collision[/code]). [code]collision[/code] is a child of [code]body[/code] which is a child of [code]node[/code]. Only [code]body[/code] is owned by [code]node[/code] and [method pack] will therefore only save those two nodes, but not [code]collision[/code]. [codeblocks] [gdscript] # Create the objects. diff --git a/doc/classes/PacketPeerUDP.xml b/doc/classes/PacketPeerUDP.xml index 12d3178797..05b6e646c0 100644 --- a/doc/classes/PacketPeerUDP.xml +++ b/doc/classes/PacketPeerUDP.xml @@ -4,7 +4,32 @@ UDP packet peer. </brief_description> <description> - UDP packet peer. Can be used to send raw UDP packets as well as [Variant]s. + UDP packet peer. Can be used to send and receive raw UDP packets as well as [Variant]s. + [b]Example:[/b] Send a packet: + [codeblock] + var peer = PacketPeerUDP.new() + + # Optionally, you can select the local port used to send the packet. + peer.bind(4444) + + peer.set_dest_address("1.1.1.1", 4433) + peer.put_packet("hello".to_utf8_buffer()) + [/codeblock] + [b]Example:[/b] Listen for packets: + [codeblock] + var peer + + func _ready(): + peer = PacketPeerUDP.new() + peer.bind(4433) + + + func _process(_delta): + if peer.get_available_packet_count() > 0: + var array_bytes = peer.get_packet() + var packet_string = array_bytes.get_string_from_ascii() + print("Received message: ", packet_string) + [/codeblock] [b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. </description> <tutorials> diff --git a/doc/classes/PhysicalBone3D.xml b/doc/classes/PhysicalBone3D.xml index ca1948e8e1..eda9fd6af5 100644 --- a/doc/classes/PhysicalBone3D.xml +++ b/doc/classes/PhysicalBone3D.xml @@ -21,6 +21,9 @@ <return type="void" /> <param index="0" name="impulse" type="Vector3" /> <description> + Applies a directional impulse without affecting rotation. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_integrate_forces" functions otherwise). + This is equivalent to using [method apply_impulse] at the body's center of mass. </description> </method> <method name="apply_impulse"> @@ -28,21 +31,27 @@ <param index="0" name="impulse" type="Vector3" /> <param index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> + Applies a positioned impulse to the PhysicsBone3D. + An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_integrate_forces" functions otherwise). + [param position] is the offset from the PhysicsBone3D origin in global coordinates. </description> </method> <method name="get_bone_id" qualifiers="const"> <return type="int" /> <description> + Returns the unique identifier of the PhysicsBone3D. </description> </method> <method name="get_simulate_physics"> <return type="bool" /> <description> + Returns [code]true[/code] if the PhysicsBone3D is allowed to simulate physics. </description> </method> <method name="is_simulating_physics"> <return type="bool" /> <description> + Returns [code]true[/code] if the PhysicsBone3D is currently simulating physics. </description> </method> </methods> @@ -75,7 +84,7 @@ The body's friction, from [code]0[/code] (frictionless) to [code]1[/code] (max friction). </member> <member name="gravity_scale" type="float" setter="set_gravity_scale" getter="get_gravity_scale" default="1.0"> - This is multiplied by the global 3D gravity setting found in [b]Project > Project Settings > Physics > 3d[/b] to produce the body's gravity. For example, a value of 1 will be normal gravity, 2 will apply double gravity, and 0.5 will apply half gravity to this object. + This is multiplied by [member ProjectSettings.physics/3d/default_gravity] to produce this body's gravity. For example, a value of [code]1.0[/code] will apply normal gravity, [code]2.0[/code] will apply double the gravity, and [code]0.5[/code] will apply half the gravity to this body. </member> <member name="joint_offset" type="Transform3D" setter="set_joint_offset" getter="get_joint_offset" default="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"> Sets the joint's transform. @@ -87,7 +96,7 @@ Sets the joint type. See [enum JointType] for possible values. </member> <member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.0"> - Damps the body's movement. By default, the body will use the [b]Default Linear Damp[/b] in [b]Project > Project Settings > Physics > 3d[/b] or any value override set by an [Area3D] the body is in. Depending on [member linear_damp_mode], you can set [member linear_damp] to be added to or to replace the body's damping value. + Damps the body's movement. By default, the body will use [member ProjectSettings.physics/3d/default_linear_damp] or any value override set by an [Area3D] the body is in. Depending on [member linear_damp_mode], [member linear_damp] may be added to or replace the body's damping value. See [member ProjectSettings.physics/3d/default_linear_damp] for more details about damping. </member> <member name="linear_damp_mode" type="int" setter="set_linear_damp_mode" getter="get_linear_damp_mode" enum="PhysicalBone3D.DampMode" default="0"> @@ -108,16 +117,22 @@ In this mode, the body's damping value replaces any value set in areas or the default value. </constant> <constant name="JOINT_TYPE_NONE" value="0" enum="JointType"> + No joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_PIN" value="1" enum="JointType"> + A pin joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_CONE" value="2" enum="JointType"> + A cone joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_HINGE" value="3" enum="JointType"> + A hinge joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_SLIDER" value="4" enum="JointType"> + A slider joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_6DOF" value="5" enum="JointType"> + A 6 degrees of freedom joint is applied to the PhysicsBone3D. </constant> </constants> </class> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index d73cda7460..9fd47cf7f5 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -135,8 +135,6 @@ Adds a new multistate item with text [param label]. Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. The default value is defined by [param default_state]. An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. - [b]Note:[/b] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. - Example usage: [codeblock] func _ready(): add_multistate_item("Item", 3, 0) @@ -152,6 +150,7 @@ print("Third state") ) [/codeblock] + [b]Note:[/b] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. </description> </method> <method name="add_radio_check_item"> diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index 58a8da12da..ba48d2dcf5 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -18,7 +18,8 @@ <method name="get_mesh_arrays" qualifiers="const"> <return type="Array" /> <description> - Returns mesh arrays used to constitute surface of [Mesh]. The result can be passed to [method ArrayMesh.add_surface_from_arrays] to create a new surface. For example: + Returns the mesh arrays used to make up the surface of this primitive mesh. + [b]Example:[/b] Pass the result to [method ArrayMesh.add_surface_from_arrays] to create a new surface: [codeblocks] [gdscript] var c = CylinderMesh.new() diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index fff6c8d3bb..91961fcf02 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -103,7 +103,7 @@ <param index="0" name="name" type="StringName" /> <description> Similar to [method get_setting], but applies feature tag overrides if any exists and is valid. - [b]Example:[/b] If the setting override [code]"application/config/name.windows"[/code] exists, and the following code is executed on a [i]Windows[/i] operating system, the overridden setting is printed instead: + [b]Example:[/b] If the setting override [code]"application/config/name.windows"[/code] exists, and the following code is executed on a [i]Windows[/i] operating system, the overridden setting is printed instead: [codeblocks] [gdscript] print(ProjectSettings.get_setting_with_override("application/config/name")) @@ -2474,10 +2474,10 @@ Number of blur passes to use when computing screen-space ambient occlusion. A higher number will result in a smoother look, but will be slower to compute and will have less high-frequency detail. </member> <member name="rendering/environment/ssao/fadeout_from" type="float" setter="" getter="" default="50.0"> - Distance at which the screen-space ambient occlusion effect starts to fade out. Use this hide ambient occlusion at great distances. + Distance at which the screen-space ambient occlusion effect starts to fade out. Use this hide ambient occlusion from far away. </member> <member name="rendering/environment/ssao/fadeout_to" type="float" setter="" getter="" default="300.0"> - Distance at which the screen-space ambient occlusion is fully faded out. Use this hide ambient occlusion at great distances. + Distance at which the screen-space ambient occlusion is fully faded out. Use this hide ambient occlusion from far away. </member> <member name="rendering/environment/ssao/half_size" type="bool" setter="" getter="" default="true"> If [code]true[/code], screen-space ambient occlusion will be rendered at half size and then upscaled before being added to the scene. This is significantly faster but may miss small details. If [code]false[/code], screen-space ambient occlusion will be rendered at full size. @@ -2492,10 +2492,10 @@ Number of blur passes to use when computing screen-space indirect lighting. A higher number will result in a smoother look, but will be slower to compute and will have less high-frequency detail. </member> <member name="rendering/environment/ssil/fadeout_from" type="float" setter="" getter="" default="50.0"> - Distance at which the screen-space indirect lighting effect starts to fade out. Use this hide screen-space indirect lighting at great distances. + Distance at which the screen-space indirect lighting effect starts to fade out. Use this to hide screen-space indirect lighting from far away. </member> <member name="rendering/environment/ssil/fadeout_to" type="float" setter="" getter="" default="300.0"> - Distance at which the screen-space indirect lighting is fully faded out. Use this hide screen-space indirect lighting at great distances. + Distance at which the screen-space indirect lighting is fully faded out. Use this to hide screen-space indirect lighting from far away. </member> <member name="rendering/environment/ssil/half_size" type="bool" setter="" getter="" default="true"> If [code]true[/code], screen-space indirect lighting will be rendered at half size and then upscaled before being added to the scene. This is significantly faster but may miss small details and may result in some objects appearing to glow at their edges. @@ -2778,6 +2778,8 @@ [b]Forward Plus[/b]: High-end renderer designed for Desktop devices. Has a higher base overhead, but scales well with complex scenes. Not suitable for older devices or mobile. [b]Mobile[/b]: Modern renderer designed for mobile devices. Has a lower base overhead than Forward Plus, but does not scale as well to large scenes with many elements. [b]GL Compatibility[/b]: Low-end renderer designed for older devices. Based on the limitations of the OpenGL 3.3/ OpenGL ES 3.0 / WebGL 2 APIs. + This can be overridden using the [code]--rendering-method <method>[/code] command line argument. + [b]Note:[/b] The actual rendering method may be automatically changed by the engine as a result of a fallback, or a user-specified command line argument. To get the actual rendering method that is used at runtime, use [method RenderingServer.get_current_rendering_method] instead of reading this project setting's value. </member> <member name="rendering/renderer/rendering_method.mobile" type="String" setter="" getter="" default=""mobile""> Override for [member rendering/renderer/rendering_method] on mobile devices. @@ -2801,7 +2803,8 @@ Depending on the complexity of scenes, this value may be lowered or may need to be raised. </member> <member name="rendering/rendering_device/driver" type="String" setter="" getter=""> - Sets the driver to be used by the renderer when using a RenderingDevice-based renderer like the clustered renderer or the mobile renderer. This property can not be edited directly, instead, set the driver using the platform-specific overrides. + Sets the driver to be used by the renderer when using a RenderingDevice-based renderer like the clustered renderer or the mobile renderer. This property can't be edited directly. Instead, set the driver using the platform-specific overrides. This can be overridden using the [code]--rendering-driver <driver>[/code] command line argument. + [b]Note:[/b] The actual rendering driver may be automatically changed by the engine as a result of a fallback, or a user-specified command line argument. To get the actual rendering driver that is used at runtime, use [method RenderingServer.get_current_rendering_driver_name] instead of reading this project setting's value. </member> <member name="rendering/rendering_device/driver.android" type="String" setter="" getter=""> Android override for [member rendering/rendering_device/driver]. @@ -2890,11 +2893,11 @@ If [code]true[/code], forces vertex shading for all rendering. This can increase performance a lot, but also reduces quality immensely. Can be used to optimize performance on low-end mobile devices. </member> <member name="rendering/textures/canvas_textures/default_texture_filter" type="int" setter="" getter="" default="1"> - The default texture filtering mode to use on [CanvasItem]s. + The default texture filtering mode to use for [CanvasItem]s built-in texture. In shaders, this texture is accessed as [code]TEXTURE[/code]. [b]Note:[/b] For pixel art aesthetics, see also [member rendering/2d/snap/snap_2d_vertices_to_pixel] and [member rendering/2d/snap/snap_2d_transforms_to_pixel]. </member> <member name="rendering/textures/canvas_textures/default_texture_repeat" type="int" setter="" getter="" default="0"> - The default texture repeating mode to use on [CanvasItem]s. + The default texture repeating mode to use for [CanvasItem]s built-in texture. In shaders, this texture is accessed as [code]TEXTURE[/code]. </member> <member name="rendering/textures/decals/filter" type="int" setter="" getter="" default="3"> The filtering quality to use for [Decal] nodes. When using one of the anisotropic filtering modes, the anisotropic filtering level is controlled by [member rendering/textures/default_filters/anisotropic_filtering_level]. diff --git a/doc/classes/Projection.xml b/doc/classes/Projection.xml index 1665660da3..f781083abf 100644 --- a/doc/classes/Projection.xml +++ b/doc/classes/Projection.xml @@ -14,7 +14,8 @@ <constructor name="Projection"> <return type="Projection" /> <description> - Constructs a default-initialized [Projection] set to [constant IDENTITY]. + Constructs a default-initialized [Projection] identical to [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Projection] identical to [constant ZERO]. </description> </constructor> <constructor name="Projection"> diff --git a/doc/classes/Quaternion.xml b/doc/classes/Quaternion.xml index 665c6335f2..c74a6453e0 100644 --- a/doc/classes/Quaternion.xml +++ b/doc/classes/Quaternion.xml @@ -22,6 +22,7 @@ <return type="Quaternion" /> <description> Constructs a [Quaternion] identical to the [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Quaternion] with all of its components set to [code]0.0[/code]. </description> </constructor> <constructor name="Quaternion"> diff --git a/doc/classes/RDTextureFormat.xml b/doc/classes/RDTextureFormat.xml index f8de7feda0..ac875ab7c1 100644 --- a/doc/classes/RDTextureFormat.xml +++ b/doc/classes/RDTextureFormat.xml @@ -13,12 +13,14 @@ <return type="void" /> <param index="0" name="format" type="int" enum="RenderingDevice.DataFormat" /> <description> + Adds [param format] as a valid format for the corresponding [RDTextureView]'s [member RDTextureView.format_override] property. If any format is added as shareable, then the main [member format] must also be added. </description> </method> <method name="remove_shareable_format"> <return type="void" /> <param index="0" name="format" type="int" enum="RenderingDevice.DataFormat" /> <description> + Removes [param format] from the list of valid formats that the corresponding [RDTextureView]'s [member RDTextureView.format_override] property can be set to. </description> </method> </methods> diff --git a/doc/classes/RDTextureView.xml b/doc/classes/RDTextureView.xml index 30b6bfedf5..bd8102d553 100644 --- a/doc/classes/RDTextureView.xml +++ b/doc/classes/RDTextureView.xml @@ -10,7 +10,7 @@ </tutorials> <members> <member name="format_override" type="int" setter="set_format_override" getter="get_format_override" enum="RenderingDevice.DataFormat" default="218"> - Optional override for the data format to return sampled values in. The default value of [constant RenderingDevice.DATA_FORMAT_MAX] does not override the format. + Optional override for the data format to return sampled values in. The corresponding [RDTextureFormat] must have had this added as a shareable format. The default value of [constant RenderingDevice.DATA_FORMAT_MAX] does not override the format. </member> <member name="swizzle_a" type="int" setter="set_swizzle_a" getter="get_swizzle_a" enum="RenderingDevice.TextureSwizzle" default="6"> The channel to sample when sampling the alpha channel. diff --git a/doc/classes/RenderSceneBuffersRD.xml b/doc/classes/RenderSceneBuffersRD.xml index 212a65337e..7b5aac5b61 100644 --- a/doc/classes/RenderSceneBuffersRD.xml +++ b/doc/classes/RenderSceneBuffersRD.xml @@ -61,7 +61,7 @@ <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the color texture we are rendering 3D content to. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_color_texture"> @@ -69,7 +69,7 @@ <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the color texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_depth_layer"> @@ -78,7 +78,7 @@ <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the depth texture we are rendering 3D content to. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_depth_texture"> @@ -86,7 +86,7 @@ <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the depth texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_fsr_sharpness" qualifiers="const"> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 284dc07fd4..26f80630bb 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -1548,6 +1548,20 @@ Tries to free an object in the RenderingServer. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingServer directly. </description> </method> + <method name="get_current_rendering_driver_name" qualifiers="const"> + <return type="String" /> + <description> + Returns the name of the current rendering driver. This can be [code]vulkan[/code], [code]d3d12[/code], [code]metal[/code], [code]opengl3[/code], [code]opengl3_es[/code], or [code]opengl3_angle[/code]. See also [method get_current_rendering_method]. + The rendering driver is determined by [member ProjectSettings.rendering/rendering_device/driver], the [code]--rendering-driver[/code] command line argument that overrides this project setting, or an automatic fallback that is applied depending on the hardware. + </description> + </method> + <method name="get_current_rendering_method" qualifiers="const"> + <return type="String" /> + <description> + Returns the name of the current rendering method. This can be [code]forward_plus[/code], [code]mobile[/code], or [code]gl_compatibility[/code]. See also [method get_current_rendering_driver_name]. + The rendering method is determined by [member ProjectSettings.rendering/renderer/rendering_method], the [code]--rendering-method[/code] command line argument that overrides this project setting, or an automatic fallback that is applied depending on the hardware. + </description> + </method> <method name="get_default_clear_color"> <return type="Color" /> <description> @@ -1600,7 +1614,7 @@ <return type="RID" /> <description> Returns the RID of a 256×256 texture with a testing pattern on it (in [constant Image.FORMAT_RGB8] format). This texture will be created and returned on the first call to [method get_test_texture], then it will be cached for subsequent calls. See also [method get_white_texture]. - Example of getting the test texture and applying it to a [Sprite2D] node: + [b]Example:[/b] Get the test texture and apply it to a [Sprite2D] node: [codeblock] var texture_rid = RenderingServer.get_test_texture() var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) @@ -1641,7 +1655,7 @@ <return type="RID" /> <description> Returns the ID of a 4×4 white texture (in [constant Image.FORMAT_RGB8] format). This texture will be created and returned on the first call to [method get_white_texture], then it will be cached for subsequent calls. See also [method get_test_texture]. - Example of getting the white texture and applying it to a [Sprite2D] node: + [b]Example:[/b] Get the white texture and apply it to a [Sprite2D] node: [codeblock] var texture_rid = RenderingServer.get_white_texture() var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) @@ -3514,7 +3528,7 @@ <param index="0" name="texture" type="RID" /> <description> Returns an [Image] instance from the given [param texture] [RID]. - Example of getting the test texture from [method get_test_texture] and applying it to a [Sprite2D] node: + [b]Example:[/b] Get the test texture from [method get_test_texture] and apply it to a [Sprite2D] node: [codeblock] var texture_rid = RenderingServer.get_test_texture() var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 18d4047339..0f3a231cb7 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -37,7 +37,7 @@ <return type="void" /> <description> Override this method to customize the newly duplicated resource created from [method PackedScene.instantiate], if the original's [member resource_local_to_scene] is set to [code]true[/code]. - [b]Example:[/b] Set a random [code]damage[/code] value to every local resource from an instantiated scene. + [b]Example:[/b] Set a random [code]damage[/code] value to every local resource from an instantiated scene: [codeblock] extends Resource diff --git a/doc/classes/ResourceFormatLoader.xml b/doc/classes/ResourceFormatLoader.xml index 4e4adc86c4..cdbf8b3f9a 100644 --- a/doc/classes/ResourceFormatLoader.xml +++ b/doc/classes/ResourceFormatLoader.xml @@ -57,6 +57,7 @@ <return type="int" /> <param index="0" name="path" type="String" /> <description> + Should return the unique ID for the resource associated with the given path. If this method is not overridden, a [code].uid[/code] file is generated along with the resource file, containing the unique ID. </description> </method> <method name="_handles_type" qualifiers="virtual const"> diff --git a/doc/classes/ResourceLoader.xml b/doc/classes/ResourceLoader.xml index f718ad15d8..ae862dd52f 100644 --- a/doc/classes/ResourceLoader.xml +++ b/doc/classes/ResourceLoader.xml @@ -7,6 +7,7 @@ A singleton used to load resource files from the filesystem. It uses the many [ResourceFormatLoader] classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine. [b]Note:[/b] You have to import the files into the engine first to load them using [method load]. If you want to load [Image]s at run-time, you may use [method Image.load]. If you want to import audio files, you can use the snippet described in [member AudioStreamMP3.data]. + [b]Note:[/b] Non-resource files such as plain text files cannot be read using [ResourceLoader]. Use [FileAccess] for those files instead, and be aware that non-resource files are not exported by default (see notes in the [FileAccess] class description for instructions on exporting them). </description> <tutorials> <link title="Operating System Testing Demo">https://godotengine.org/asset-library/asset/2789</link> @@ -74,6 +75,13 @@ Once a resource has been loaded by the engine, it is cached in memory for faster access, and future calls to the [method load] method will use the cached version. The cached resource can be overridden by using [method Resource.take_over_path] on a new resource for that same path. </description> </method> + <method name="list_directory"> + <return type="PackedStringArray" /> + <param index="0" name="directory_path" type="String" /> + <description> + Lists a directory (as example: "res://assets/enemies"), returning all resources contained within. The resource files are the original file names as visible in the editor before exporting. + </description> + </method> <method name="load"> <return type="Resource" /> <param index="0" name="path" type="String" /> @@ -104,7 +112,7 @@ <param index="1" name="progress" type="Array" default="[]" /> <description> Returns the status of a threaded loading operation started with [method load_threaded_request] for the resource at [param path]. See [enum ThreadLoadStatus] for possible return values. - An array variable can optionally be passed via [param progress], and will return a one-element array containing the ratio of completion of the threaded loading (between [code]0.0[/code] and [code]1.0[/code]). + An array variable can optionally be passed via [param progress], and will return a one-element array containing the ratio of completion of the threaded loading (between [code]0.0[/code] and [code]1.0[/code]). [b]Note:[/b] The recommended way of using this method is to call it during different frames (e.g., in [method Node._process], instead of a loop). </description> </method> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 2ac346b5c2..8472e57840 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -225,8 +225,8 @@ <return type="void" /> <param index="0" name="effect" type="Variant" /> <description> - Installs a custom effect. This can also be done in the RichTextLabel inspector using the [member custom_effects] property. [param effect] should be a valid [RichTextEffect]. - Example RichTextEffect: + Installs a custom effect. This can also be done in the Inspector through the [member custom_effects] property. [param effect] should be a valid [RichTextEffect]. + [b]Example:[/b] With the following script extending from [RichTextEffect]: [codeblock] # effect.gd class_name MyCustomEffect @@ -236,7 +236,7 @@ # ... [/codeblock] - Registering the above effect in RichTextLabel from script: + The above effect can be installed in [RichTextLabel] from a script: [codeblock] # rich_text_label.gd extends RichTextLabel diff --git a/doc/classes/RigidBody3D.xml b/doc/classes/RigidBody3D.xml index dae904e2a3..9a299ade57 100644 --- a/doc/classes/RigidBody3D.xml +++ b/doc/classes/RigidBody3D.xml @@ -179,7 +179,7 @@ For a body that is always frozen, use [StaticBody3D] or [AnimatableBody3D] instead. </member> <member name="gravity_scale" type="float" setter="set_gravity_scale" getter="get_gravity_scale" default="1.0"> - This is multiplied by the global 3D gravity setting found in [b]Project > Project Settings > Physics > 3d[/b] to produce RigidBody3D's gravity. For example, a value of 1 will be normal gravity, 2 will apply double gravity, and 0.5 will apply half gravity to this object. + This is multiplied by [member ProjectSettings.physics/3d/default_gravity] to produce this body's gravity. For example, a value of [code]1.0[/code] will apply normal gravity, [code]2.0[/code] will apply double the gravity, and [code]0.5[/code] will apply half the gravity to this body. </member> <member name="inertia" type="Vector3" setter="set_inertia" getter="get_inertia" default="Vector3(0, 0, 0)"> The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body on each axis. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value. diff --git a/doc/classes/SkeletonModification2DTwoBoneIK.xml b/doc/classes/SkeletonModification2DTwoBoneIK.xml index 1c7bb32f4a..d2417ba7bf 100644 --- a/doc/classes/SkeletonModification2DTwoBoneIK.xml +++ b/doc/classes/SkeletonModification2DTwoBoneIK.xml @@ -65,7 +65,7 @@ </methods> <members> <member name="flip_bend_direction" type="bool" setter="set_flip_bend_direction" getter="get_flip_bend_direction" default="false"> - If [code]true[/code], the bones in the modification will blend outward as opposed to inwards when contracting. If [code]false[/code], the bones will bend inwards when contracting. + If [code]true[/code], the bones in the modification will bend outward as opposed to inwards when contracting. If [code]false[/code], the bones will bend inwards when contracting. </member> <member name="target_maximum_distance" type="float" setter="set_target_maximum_distance" getter="get_target_maximum_distance" default="0.0"> The maximum distance the target can be at. If the target is farther than this distance, the modification will solve as if it's at this maximum distance. When set to [code]0[/code], the modification will solve without distance constraints. diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 44795af473..e59734cf03 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -270,12 +270,12 @@ print("Visible {visible}, position {position}".format(node)) [/codeblock] See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. - [b]Note:[/b] The replacement of placeholders is not done all at once, instead each placeholder is replaced in the order they are passed, this means that if one of the replacement strings contains a key it will also be replaced. This can be very powerful, but can also cause unexpected results if you are not careful. If you do not need to perform replacement in the replacement strings, make sure your replacements do not contain placeholders to ensure reliable results. + [b]Note:[/b] Each replacement is done sequentially for each element of [param values], [b]not[/b] all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure [param values]'s elements do not contain placeholders. [codeblock] - print("{0} {1}".format(["{1}", "x"])) # Prints "x x". - print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". - print("{foo} {bar}".format({"foo": "{bar}", "bar": "baz"})) # Prints "baz baz". - print("{foo} {bar}".format({"bar": "baz", "foo": "{bar}"})) # Prints "{bar} baz". + print("{0} {1}".format(["{1}", "x"])) # Prints "x x". + print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". + print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c". + print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c". [/codeblock] [b]Note:[/b] In C#, it's recommended to [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]interpolate strings with "$"[/url], instead. </description> @@ -887,7 +887,7 @@ <return type="float" /> <param index="0" name="text" type="String" /> <description> - Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. + Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sørensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. [codeblock] print("ABC123".similarity("ABC123")) # Prints 1.0 print("ABC123".similarity("XYZ456")) # Prints 0.0 diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index 3a2b492496..4982bc36a8 100644 --- a/doc/classes/StringName.xml +++ b/doc/classes/StringName.xml @@ -247,6 +247,13 @@ print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) [/codeblock] See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. + [b]Note:[/b] Each replacement is done sequentially for each element of [param values], [b]not[/b] all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure [param values]'s elements do not contain placeholders. + [codeblock] + print("{0} {1}".format(["{1}", "x"])) # Prints "x x". + print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". + print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c". + print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c". + [/codeblock] [b]Note:[/b] In C#, it's recommended to [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]interpolate strings with "$"[/url], instead. </description> </method> @@ -299,7 +306,7 @@ <param index="0" name="delimiter" type="String" /> <param index="1" name="slice" type="int" /> <description> - Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist. + Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns the original string if [param delimiter] does not occur in the string. Returns an empty string if the [param slice] does not exist. This is faster than [method split], if you only need one substring. [codeblock] print("i/am/example/hi".get_slice("/", 2)) # Prints "example" @@ -782,7 +789,7 @@ <return type="float" /> <param index="0" name="text" type="String" /> <description> - Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. + Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sørensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. [codeblock] print("ABC123".similarity("ABC123")) # Prints 1.0 print("ABC123".similarity("XYZ456")) # Prints 0.0 @@ -871,7 +878,7 @@ <method name="to_ascii_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. + Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. This is the inverse of [method PackedByteArray.get_string_from_ascii]. </description> </method> <method name="to_camel_case" qualifiers="const"> @@ -885,11 +892,11 @@ <description> Converts the string representing a decimal number into a [float]. This method stops on the first non-number character, except the first decimal point ([code].[/code]) and the exponent letter ([code]e[/code]). See also [method is_valid_float]. [codeblock] - var a = "12.35".to_float() # a is 12.35 - var b = "1.2.3".to_float() # b is 1.2 - var c = "12xy3".to_float() # c is 12.0 - var d = "1e3".to_float() # d is 1000.0 - var e = "Hello!".to_int() # e is 0.0 + var a = "12.35".to_float() # a is 12.35 + var b = "1.2.3".to_float() # b is 1.2 + var c = "12xy3".to_float() # c is 12.0 + var d = "1e3".to_float() # d is 1000.0 + var e = "Hello!".to_float() # e is 0.0 [/codeblock] </description> </method> @@ -945,25 +952,25 @@ <method name="to_utf8_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. This is the inverse of [method PackedByteArray.get_string_from_utf8]. </description> </method> <method name="to_utf16_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_utf16]. </description> </method> <method name="to_utf32_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_utf32]. </description> </method> <method name="to_wchar_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/Wide_character]wide character[/url] ([code]wchar_t[/code], UTF-16 on Windows, UTF-32 on other platforms) encoded [PackedByteArray]. + Converts the string to a [url=https://en.wikipedia.org/wiki/Wide_character]wide character[/url] ([code]wchar_t[/code], UTF-16 on Windows, UTF-32 on other platforms) encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_wchar]. </description> </method> <method name="trim_prefix" qualifiers="const"> @@ -990,7 +997,7 @@ <method name="uri_decode" qualifiers="const"> <return type="String" /> <description> - Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. + Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. See also [method uri_encode]. [codeblocks] [gdscript] var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" @@ -1006,7 +1013,7 @@ <method name="uri_encode" qualifiers="const"> <return type="String" /> <description> - Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. + Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. See also [method uri_decode]. [codeblocks] [gdscript] var prefix = "$DOCS_URL/?highlight=" diff --git a/doc/classes/StyleBoxTexture.xml b/doc/classes/StyleBoxTexture.xml index 14bceb4d4c..07d4b13f36 100644 --- a/doc/classes/StyleBoxTexture.xml +++ b/doc/classes/StyleBoxTexture.xml @@ -80,9 +80,9 @@ Modulates the color of the texture when this style box is drawn. </member> <member name="region_rect" type="Rect2" setter="set_region_rect" getter="get_region_rect" default="Rect2(0, 0, 0, 0)"> - Species a sub-region of the texture to use. - This is equivalent to first wrapping the texture in an [AtlasTexture] with the same region. - If empty ([code]Rect2(0, 0, 0, 0)[/code]), the whole texture will be used. + The region to use from the [member texture]. + This is equivalent to first wrapping the [member texture] in an [AtlasTexture] with the same region. + If empty ([code]Rect2(0, 0, 0, 0)[/code]), the whole [member texture] is used. </member> <member name="texture" type="Texture2D" setter="set_texture" getter="get_texture"> The texture to use when drawing this style box. diff --git a/doc/classes/SyntaxHighlighter.xml b/doc/classes/SyntaxHighlighter.xml index 27cee26c50..22d20d24e5 100644 --- a/doc/classes/SyntaxHighlighter.xml +++ b/doc/classes/SyntaxHighlighter.xml @@ -41,11 +41,11 @@ <return type="Dictionary" /> <param index="0" name="line" type="int" /> <description> - Returns syntax highlighting data for a single line. If the line is not cached, calls [method _get_line_syntax_highlighting] to calculate the data. - The return [Dictionary] is column number to [Dictionary]. The column number notes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region, currently only the key "color" is supported. - [b]Example return:[/b] + Returns the syntax highlighting data for the line at index [param line]. If the line is not cached, calls [method _get_line_syntax_highlighting] first to calculate the data. + Each entry is a column number containing a nested [Dictionary]. The column number denotes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region. Currently only the key [code]"color"[/code] is supported. + [b]Example:[/b] Possible return value. This means columns [code]0[/code] to [code]4[/code] should be red, and columns [code]5[/code] to the end of the line should be green: [codeblock] - var color_map = { + { 0: { "color": Color(1, 0, 0) }, @@ -54,7 +54,6 @@ } } [/codeblock] - This will color columns 0-4 red, and columns 5-eol in green. </description> </method> <method name="get_text_edit" qualifiers="const"> diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 7a4bef5747..13721d9d62 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -124,7 +124,6 @@ <return type="void" /> <description> Starts an edit for multiple carets. The edit must be ended with [method end_multicaret_edit]. Multicaret edits can be used to edit text at multiple carets and delay merging the carets until the end, so the caret indexes aren't affected immediately. [method begin_multicaret_edit] and [method end_multicaret_edit] can be nested, and the merge will happen at the last [method end_multicaret_edit]. - Example usage: [codeblock] begin_complex_operation() begin_multicaret_edit() @@ -764,7 +763,8 @@ <return type="bool" /> <param index="0" name="caret_index" type="int" default="0" /> <description> - Returns [code]true[/code] if the caret is visible on the screen. + Returns [code]true[/code] if the caret is visible, [code]false[/code] otherwise. A caret will be considered hidden if it is outside the scrollable area when scrolling is enabled. + [b]Note:[/b] [method is_caret_visible] does not account for a caret being off-screen if it is still within the scrollable area. It will return [code]true[/code] even if the caret is off-screen as long as it meets [TextEdit]'s own conditions for being visible. This includes uses of [member scroll_fit_content_width] and [member scroll_fit_content_height] that cause the [TextEdit] to expand beyond the viewport's bounds. </description> </method> <method name="is_dragging_cursor" qualifiers="const"> diff --git a/doc/classes/TileMapLayer.xml b/doc/classes/TileMapLayer.xml index 6cbec9c2aa..43708ca142 100644 --- a/doc/classes/TileMapLayer.xml +++ b/doc/classes/TileMapLayer.xml @@ -22,6 +22,21 @@ [b]Note:[/b] If the properties of [param tile_data] object should change over time, use [method notify_runtime_tile_data_update] to notify the [TileMapLayer] it needs an update. </description> </method> + <method name="_update_cells" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="coords" type="Vector2i[]" /> + <param index="1" name="forced_cleanup" type="bool" /> + <description> + Called when this [TileMapLayer]'s cells need an internal update. This update may be caused from individual cells being modified or by a change in the [member tile_set] (causing all cells to be queued for an update). The first call to this function is always for initializing all the [TileMapLayer]'s cells. [param coords] contains the coordinates of all modified cells, roughly in the order they were modified. [param forced_cleanup] is [code]true[/code] when the [TileMapLayer]'s internals should be fully cleaned up. This is the case when: + - The layer is disabled; + - The layer is not visible; + - [member tile_set] is set to [code]null[/code]; + - The node is removed from the tree; + - The node is freed. + Note that any internal update happening while one of these conditions is verified is considered to be a "cleanup". See also [method update_internals]. + [b]Warning:[/b] Implementing this method may degrade the [TileMapLayer]'s performance. + </description> + </method> <method name="_use_tile_data_runtime_update" qualifiers="virtual"> <return type="bool" /> <param index="0" name="coords" type="Vector2i" /> @@ -120,7 +135,7 @@ <return type="Vector2i[]" /> <param index="0" name="coords" type="Vector2i" /> <description> - Returns the list of all neighboring cells to the one at [param coords]. + Returns the list of all neighboring cells to the one at [param coords]. Any neighboring cell is one that is touching edges, so for a square cell 4 cells would be returned, for a hexagon 6 cells are returned. </description> </method> <method name="get_used_cells" qualifiers="const"> diff --git a/doc/classes/TouchScreenButton.xml b/doc/classes/TouchScreenButton.xml index 5052518583..faeaaba5b6 100644 --- a/doc/classes/TouchScreenButton.xml +++ b/doc/classes/TouchScreenButton.xml @@ -5,7 +5,7 @@ </brief_description> <description> TouchScreenButton allows you to create on-screen buttons for touch devices. It's intended for gameplay use, such as a unit you have to touch to move. Unlike [Button], TouchScreenButton supports multitouch out of the box. Several TouchScreenButtons can be pressed at the same time with touch input. - This node inherits from [Node2D]. Unlike with [Control] nodes, you cannot set anchors on it. If you want to create menus or user interfaces, you may want to use [Button] nodes instead. To make button nodes react to touch events, you can enable the Emulate Mouse option in the Project Settings. + This node inherits from [Node2D]. Unlike with [Control] nodes, you cannot set anchors on it. If you want to create menus or user interfaces, you may want to use [Button] nodes instead. To make button nodes react to touch events, you can enable [member ProjectSettings.input_devices/pointing/emulate_mouse_from_touch] in the Project Settings. You can configure TouchScreenButton to be visible only on touch devices, helping you develop your game both for desktop and mobile devices. </description> <tutorials> diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml index 756716433e..665e5e9d67 100644 --- a/doc/classes/Transform2D.xml +++ b/doc/classes/Transform2D.xml @@ -20,6 +20,7 @@ <return type="Transform2D" /> <description> Constructs a [Transform2D] identical to [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Transform2D] with all of its components set to [constant Vector2.ZERO]. </description> </constructor> <constructor name="Transform2D"> diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index 30c141659a..98e9d56adb 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -21,6 +21,7 @@ <return type="Transform3D" /> <description> Constructs a [Transform3D] identical to the [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Transform3D] with its [member origin] and the components of its [member basis] set to [constant Vector3.ZERO]. </description> </constructor> <constructor name="Transform3D"> @@ -128,7 +129,7 @@ <param index="1" name="angle" type="float" /> <description> Returns a copy of this transform rotated around the given [param axis] by the given [param angle] (in radians). - The [param axis] must be a normalized vector. + The [param axis] must be a normalized vector in the transform's local coordinate system. For example, to rotate around the local X-axis, use [constant Vector3.RIGHT]. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding rotation transform [code]R[/code] from the right, i.e., [code]X * R[/code]. This can be seen as transforming with respect to the local frame. </description> diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml index 86a8130acc..147d9fa4bd 100644 --- a/doc/classes/Tween.xml +++ b/doc/classes/Tween.xml @@ -218,8 +218,14 @@ <return type="Tween" /> <param index="0" name="ease" type="int" enum="Tween.EaseType" /> <description> - Sets the default ease type for [PropertyTweener]s and [MethodTweener]s animated by this [Tween]. - If not specified, the default value is [constant EASE_IN_OUT]. + Sets the default ease type for [PropertyTweener]s and [MethodTweener]s appended after this method. + Before this method is called, the default ease type is [constant EASE_IN_OUT]. + [codeblock] + var tween = create_tween() + tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Uses EASE_IN_OUT. + tween.set_ease(Tween.EASE_IN) + tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Uses EASE_IN. + [/codeblock] </description> </method> <method name="set_loops"> @@ -271,14 +277,36 @@ <return type="Tween" /> <param index="0" name="trans" type="int" enum="Tween.TransitionType" /> <description> - Sets the default transition type for [PropertyTweener]s and [MethodTweener]s animated by this [Tween]. - If not specified, the default value is [constant TRANS_LINEAR]. + Sets the default transition type for [PropertyTweener]s and [MethodTweener]s appended after this method. + Before this method is called, the default transition type is [constant TRANS_LINEAR]. + [codeblock] + var tween = create_tween() + tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Uses TRANS_LINEAR. + tween.set_trans(Tween.TRANS_SINE) + tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Uses TRANS_SINE. + [/codeblock] </description> </method> <method name="stop"> <return type="void" /> <description> Stops the tweening and resets the [Tween] to its initial state. This will not remove any appended [Tweener]s. + [b]Note:[/b] This does [i]not[/i] reset targets of [PropertyTweener]s to their values when the [Tween] first started. + [codeblock] + var tween = create_tween() + + # Will move from 0 to 500 over 1 second. + position.x = 0.0 + tween.tween_property(self, "position:x", 500, 1.0) + + # Will be at (about) 250 when the timer finishes. + await get_tree().create_timer(0.5).timeout + + # Will now move from (about) 250 to 500 over 1 second, + # thus at half the speed as before. + tween.stop() + tween.play() + [/codeblock] [b]Note:[/b] If a Tween is stopped and not bound to any node, it will exist indefinitely until manually started or invalidated. If you lose a reference to such Tween, you can retrieve it using [method SceneTree.get_processed_tweens]. </description> </method> diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index 02110f0162..424941b842 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -725,8 +725,6 @@ <param index="0" name="files" type="PackedStringArray" /> <description> Emitted when files are dragged from the OS file manager and dropped in the game window. The argument is a list of file paths. - Note that this method only works with native windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. - Example usage: [codeblock] func _ready(): get_viewport().files_dropped.connect(on_files_dropped) @@ -734,6 +732,7 @@ func on_files_dropped(files): print(files) [/codeblock] + [b]Note:[/b] This signal only works with native windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. </description> </signal> <signal name="focus_entered"> |