diff options
Diffstat (limited to 'doc/classes')
61 files changed, 281 insertions, 135 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 35e1933473..b06c28311a 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -196,7 +196,7 @@ <return type="Variant" /> <param index="0" name="x" type="Variant" /> <description> - Rounds [param x] upward (towards positive infinity), returning the smallest whole number that is not less than [param x]. Supported types: [int], [float], [Vector2], [Vector3], [Vector4]. + Rounds [param x] upward (towards positive infinity), returning the smallest whole number that is not less than [param x]. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] var i = ceil(1.45) # i is 2.0 i = ceil(1.001) # i is 2.0 @@ -421,7 +421,7 @@ <return type="Variant" /> <param index="0" name="x" type="Variant" /> <description> - Rounds [param x] downward (towards negative infinity), returning the largest whole number that is not more than [param x]. Supported types: [int], [float], [Vector2], [Vector3], [Vector4]. + Rounds [param x] downward (towards negative infinity), returning the largest whole number that is not more than [param x]. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] var a = floor(2.99) # a is 2.0 a = floor(-2.99) # a is -3.0 @@ -1133,7 +1133,7 @@ <return type="Variant" /> <param index="0" name="x" type="Variant" /> <description> - Rounds [param x] to the nearest whole number, with halfway cases rounded away from 0. Supported types: [int], [float], [Vector2], [Vector3], [Vector4]. + Rounds [param x] to the nearest whole number, with halfway cases rounded away from 0. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] round(2.4) # Returns 2 round(2.5) # Returns 3 diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml index a803e4f106..c1c637d2d6 100644 --- a/doc/classes/AABB.xml +++ b/doc/classes/AABB.xml @@ -245,7 +245,9 @@ <return type="AABB" /> <param index="0" name="right" type="Transform3D" /> <description> - Inversely transforms (multiplies) the [AABB] by the given [Transform3D] transformation matrix. + Inversely transforms (multiplies) the [AABB] by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]aabb * transform[/code] is equivalent to [code]transform.inverse() * aabb[/code]. See [method Transform3D.inverse]. + For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * aabb[/code] can be used instead. See [method Transform3D.affine_inverse]. </description> </operator> <operator name="operator =="> diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index d2b2c1fe47..15f6b16439 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -257,7 +257,7 @@ <param index="0" name="track_idx" type="int" /> <param index="1" name="to_animation" type="Animation" /> <description> - Adds a new track that is a copy of the given track from [param to_animation]. + Adds a new track to [param to_animation] that is a copy of the given track from this animation. </description> </method> <method name="find_track" qualifiers="const"> diff --git a/doc/classes/AnimationLibrary.xml b/doc/classes/AnimationLibrary.xml index d457a858ab..7f87ea4616 100644 --- a/doc/classes/AnimationLibrary.xml +++ b/doc/classes/AnimationLibrary.xml @@ -54,10 +54,6 @@ </description> </method> </methods> - <members> - <member name="_data" type="Dictionary" setter="_set_data" getter="_get_data" default="{}"> - </member> - </members> <signals> <signal name="animation_added"> <param index="0" name="name" type="StringName" /> diff --git a/doc/classes/AudioStreamGeneratorPlayback.xml b/doc/classes/AudioStreamGeneratorPlayback.xml index 185b89d760..88c5cf6dbe 100644 --- a/doc/classes/AudioStreamGeneratorPlayback.xml +++ b/doc/classes/AudioStreamGeneratorPlayback.xml @@ -33,6 +33,7 @@ <method name="get_skips" qualifiers="const"> <return type="int" /> <description> + Returns the number of times the playback skipped due to a buffer underrun in the audio sample data. This value is reset at the start of the playback. </description> </method> <method name="push_buffer"> diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index 72bfc2dcc7..c3295d854f 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -737,7 +737,7 @@ The object's X axis will always face the camera. </constant> <constant name="BILLBOARD_PARTICLES" value="3" enum="BillboardMode"> - Used for particle systems when assigned to [GPUParticles3D] and [CPUParticles3D] nodes. Enables [code]particles_anim_*[/code] properties. + Used for particle systems when assigned to [GPUParticles3D] and [CPUParticles3D] nodes (flipbook animation). Enables [code]particles_anim_*[/code] properties. The [member ParticleProcessMaterial.anim_speed_min] or [member CPUParticles3D.anim_speed_min] should also be set to a value bigger than zero for the animation to play. </constant> <constant name="TEXTURE_CHANNEL_RED" value="0" enum="TextureChannel"> diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index bf0534ab1e..d7782a816d 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -132,6 +132,7 @@ Font size of the [Button]'s text. </theme_item> <theme_item name="icon" data_type="icon" type="Texture2D"> + Default icon for the [Button]. Appears only if [member icon] is not assigned. </theme_item> <theme_item name="disabled" data_type="style" type="StyleBox"> [StyleBox] used when the [Button] is disabled. diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 84efd11b43..5a2df0e8a4 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -44,7 +44,7 @@ <param index="7" name="antialiased" type="bool" default="false" /> <description> Draws an unfilled arc between the given angles with a uniform [param color] and [param width] and optional antialiasing (supported only for positive [param width]). The larger the value of [param point_count], the smoother the curve. See also [method draw_circle]. - If [param width] is negative, then the arc is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. + If [param width] is negative, it will be ignored and the arc will be drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. The arc is drawn from [param start_angle] towards the value of [param end_angle] so in clockwise direction if [code]start_angle < end_angle[/code] and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of [param start_angle] and [param end_angle] is greater than [constant @GDScript.TAU] radians, then a full circle arc is drawn (i.e. arc will not overlap itself). </description> </method> @@ -246,7 +246,7 @@ <param index="3" name="antialiased" type="bool" default="false" /> <description> Draws interconnected line segments with a uniform [param color] and [param width] and optional antialiasing (supported only for positive [param width]). When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline] instead. See also [method draw_polygon]. - If [param width] is negative, the polyline is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. + If [param width] is negative, it will be ignored and the polyline will be drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. </description> </method> <method name="draw_polyline_colors"> @@ -257,7 +257,7 @@ <param index="3" name="antialiased" type="bool" default="false" /> <description> Draws interconnected line segments with a uniform [param width], point-by-point coloring, and optional antialiasing (supported only for positive [param width]). Colors assigned to line points match by index between [param points] and [param colors], i.e. each line segment is filled with a gradient between the colors of the endpoints. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline_colors] instead. See also [method draw_polygon]. - If [param width] is negative, then the polyline is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. + If [param width] is negative, it will be ignored and the polyline will be drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. </description> </method> <method name="draw_primitive"> diff --git a/doc/classes/ConcavePolygonShape2D.xml b/doc/classes/ConcavePolygonShape2D.xml index 31e28bc714..6baf0f380f 100644 --- a/doc/classes/ConcavePolygonShape2D.xml +++ b/doc/classes/ConcavePolygonShape2D.xml @@ -5,7 +5,7 @@ </brief_description> <description> A 2D polyline shape, intended for use in physics. Used internally in [CollisionPolygon2D] when it's in [constant CollisionPolygon2D.BUILD_SEGMENTS] mode. - Being just a collection of interconnected line segments, [ConcavePolygonShape2D] is the most freely configurable single 2D shape. It can be used to form polygons of any nature, or even shapes that don't enclose an area. However, [ConvexPolygonShape2D] is [i]hollow[/i] even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. + Being just a collection of interconnected line segments, [ConcavePolygonShape2D] is the most freely configurable single 2D shape. It can be used to form polygons of any nature, or even shapes that don't enclose an area. However, [ConcavePolygonShape2D] is [i]hollow[/i] even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. [b]Note:[/b] When used for collision, [ConcavePolygonShape2D] is intended to work with static [CollisionShape2D] nodes like [StaticBody2D] and will likely not behave well for [CharacterBody2D]s or [RigidBody2D]s in a mode other than Static. [b]Warning:[/b] Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. [ConcavePolygonShape2D] is hollow, so it won't detect a collision. [b]Performance:[/b] Due to its complexity, [ConcavePolygonShape2D] is the slowest 2D collision shape to check collisions against. Its use should generally be limited to level geometry. If the polyline is closed, [CollisionPolygon2D]'s [constant CollisionPolygon2D.BUILD_SOLIDS] mode can be used, which decomposes the polygon into convex ones; see [ConvexPolygonShape2D]'s documentation for instructions. diff --git a/doc/classes/ConcavePolygonShape3D.xml b/doc/classes/ConcavePolygonShape3D.xml index c0d0f43010..7e4df2073f 100644 --- a/doc/classes/ConcavePolygonShape3D.xml +++ b/doc/classes/ConcavePolygonShape3D.xml @@ -5,7 +5,7 @@ </brief_description> <description> A 3D trimesh shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape3D]. - Being just a collection of interconnected triangles, [ConcavePolygonShape3D] is the most freely configurable single 3D shape. It can be used to form polyhedra of any nature, or even shapes that don't enclose a volume. However, [ConvexPolygonShape3D] is [i]hollow[/i] even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. + Being just a collection of interconnected triangles, [ConcavePolygonShape3D] is the most freely configurable single 3D shape. It can be used to form polyhedra of any nature, or even shapes that don't enclose a volume. However, [ConcavePolygonShape3D] is [i]hollow[/i] even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. [b]Note:[/b] When used for collision, [ConcavePolygonShape3D] is intended to work with static [CollisionShape3D] nodes like [StaticBody3D] and will likely not behave well for [CharacterBody3D]s or [RigidBody3D]s in a mode other than Static. [b]Warning:[/b] Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. [ConcavePolygonShape3D] is hollow, so it won't detect a collision. [b]Performance:[/b] Due to its complexity, [ConcavePolygonShape3D] is the slowest 3D collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, [ConvexPolygonShape3D] should be used. For dynamic physics bodies that need concave collision, several [ConvexPolygonShape3D]s can be used to represent its collision by using convex decomposition; see [ConvexPolygonShape3D]'s documentation for instructions. diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 21d6cb2756..b5333a045b 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -1172,10 +1172,12 @@ [b]Note:[/b] As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. </constant> <constant name="NOTIFICATION_SCROLL_BEGIN" value="47"> - Sent when this node is inside a [ScrollContainer] which has begun being scrolled. + Sent when this node is inside a [ScrollContainer] which has begun being scrolled when dragging the scrollable area [i]with a touch event[/i]. This notification is [i]not[/i] sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + [b]Note:[/b] This signal is only emitted on Android or iOS, or on desktop/web platforms when [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse] is enabled. </constant> <constant name="NOTIFICATION_SCROLL_END" value="48"> - Sent when this node is inside a [ScrollContainer] which has stopped being scrolled. + Sent when this node is inside a [ScrollContainer] which has stopped being scrolled when dragging the scrollable area [i]with a touch event[/i]. This notification is [i]not[/i] sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + [b]Note:[/b] This signal is only emitted on Android or iOS, or on desktop/web platforms when [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse] is enabled. </constant> <constant name="NOTIFICATION_LAYOUT_DIRECTION_CHANGED" value="49"> Sent when control layout direction is changed. diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index b39c5c9699..955d80fcb7 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -294,6 +294,42 @@ <param index="1" name="overwrite" type="bool" default="false" /> <description> Adds entries from [param dictionary] to this dictionary. By default, duplicate keys are not copied over, unless [param overwrite] is [code]true[/code]. + [codeblocks] + [gdscript] + var dict = { "item": "sword", "quantity": 2 } + var other_dict = { "quantity": 15, "color": "silver" } + + # Overwriting of existing keys is disabled by default. + dict.merge(other_dict) + print(dict) # { "item": "sword", "quantity": 2, "color": "silver" } + + # With overwriting of existing keys enabled. + dict.merge(other_dict, true) + print(dict) # { "item": "sword", "quantity": 15, "color": "silver" } + [/gdscript] + [csharp] + var dict = new Godot.Collections.Dictionary + { + ["item"] = "sword", + ["quantity"] = 2, + }; + + var otherDict = new Godot.Collections.Dictionary + { + ["quantity"] = 15, + ["color"] = "silver", + }; + + // Overwriting of existing keys is disabled by default. + dict.Merge(otherDict); + GD.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" } + + // With overwriting of existing keys enabled. + dict.Merge(otherDict, true); + GD.Print(dict); // { "item": "sword", "quantity": 15, "color": "silver" } + [/csharp] + [/codeblocks] + [b]Note:[/b] [method merge] is [i]not[/i] recursive. Nested dictionaries are considered as keys that can be overwritten or not depending on the value of [param overwrite], but they will never be merged together. </description> </method> <method name="size" qualifiers="const"> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 6f858942aa..50709f9ef5 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -541,7 +541,7 @@ <param index="0" name="name" type="String" /> <param index="1" name="submenu" type="PopupMenu" /> <description> - Adds a custom [PopupMenu] submenu under [b]Project > Tools >[/b] [param name]. Use [code]remove_tool_menu_item(name)[/code] on plugin clean up to remove the menu. + Adds a custom [PopupMenu] submenu under [b]Project > Tools >[/b] [param name]. Use [method remove_tool_menu_item] on plugin clean up to remove the menu. </description> </method> <method name="add_translation_parser_plugin"> diff --git a/doc/classes/EditorSpinSlider.xml b/doc/classes/EditorSpinSlider.xml index 6e5ccb4dd0..0d687ba7f5 100644 --- a/doc/classes/EditorSpinSlider.xml +++ b/doc/classes/EditorSpinSlider.xml @@ -5,6 +5,7 @@ </brief_description> <description> This [Control] node is used in the editor's Inspector dock to allow editing of numeric values. Can be used with [EditorInspectorPlugin] to recreate the same behavior. + If [member step] is [code]1[/code], the [EditorSpinSlider] will display up/down arrows, similar to [SpinBox]. If the [member step] is not [code]1[/code], a slider will be displayed instead. </description> <tutorials> </tutorials> @@ -14,7 +15,7 @@ </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> <member name="hide_slider" type="bool" setter="set_hide_slider" getter="is_hiding_slider" default="false"> - If [code]true[/code], the slider is hidden. + If [code]true[/code], the slider and up/down arrows are hidden. </member> <member name="label" type="String" setter="set_label" getter="get_label" default=""""> The text that displays to the left of the value. diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml index 54c8689ab0..08dc6a5331 100644 --- a/doc/classes/GPUParticles2D.xml +++ b/doc/classes/GPUParticles2D.xml @@ -48,14 +48,16 @@ </methods> <members> <member name="amount" type="int" setter="set_amount" getter="get_amount" default="8"> - Number of particles emitted in one emission cycle. + The number of particles to emit in one emission cycle. The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if [member amount_ratio] is decreased. + [b]Note:[/b] Changing this value will cause the particle system to restart. To avoid this, change [member amount_ratio] instead. </member> <member name="amount_ratio" type="float" setter="set_amount_ratio" getter="get_amount_ratio" default="1.0"> The ratio of particles that should actually be emitted. If set to a value lower than [code]1.0[/code], this will set the amount of emitted particles throughout the lifetime to [code]amount * amount_ratio[/code]. Unlike changing [member amount], changing [member amount_ratio] while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. [member amount_ratio] can be used to create effects that make the number of emitted particles vary over time. - [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. + [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. If you don't intend to change the number of particles emitted while the particles are emitting, make sure [member amount_ratio] is set to [code]1[/code] and change [member amount] to your liking instead. </member> <member name="collision_base_size" type="float" setter="set_collision_base_size" getter="get_collision_base_size" default="1.0"> - Multiplier for particle's collision radius. [code]1.0[/code] corresponds to the size of the sprite. + Multiplier for particle's collision radius. [code]1.0[/code] corresponds to the size of the sprite. If particles appear to sink into the ground when colliding, increase this value. If particles appear to float when colliding, decrease this value. Only effective if [member ParticleProcessMaterial.collision_mode] is [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT]. + [b]Note:[/b] Particles always have a spherical collision shape. </member> <member name="draw_order" type="int" setter="set_draw_order" getter="get_draw_order" enum="GPUParticles2D.DrawOrder" default="1"> Particle draw order. Uses [enum DrawOrder] values. @@ -74,13 +76,13 @@ </member> <member name="interp_to_end" type="float" setter="set_interp_to_end" getter="get_interp_to_end" default="0.0"> Causes all the particles in this node to interpolate towards the end of their lifetime. - [b]Note[/b]: This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. + [b]Note:[/b] This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. </member> <member name="interpolate" type="bool" setter="set_interpolate" getter="get_interpolate" default="true"> Enables particle interpolation, which makes the particle movement smoother when their [member fixed_fps] is lower than the screen refresh rate. </member> <member name="lifetime" type="float" setter="set_lifetime" getter="get_lifetime" default="1.0"> - Amount of time each particle will exist. + The amount of time each particle will exist (in seconds). The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. </member> <member name="local_coords" type="bool" setter="set_use_local_coordinates" getter="get_use_local_coordinates" default="false"> If [code]true[/code], particles use the parent node's coordinate space (known as local coordinates). This will cause particles to move and rotate along the [GPUParticles2D] node (and its parents) when it is moved or rotated. If [code]false[/code], particles use global coordinates; they will not move or rotate along the [GPUParticles2D] node (and its parents) when it is moved or rotated. @@ -101,10 +103,12 @@ Particle system's running speed scaling ratio. A value of [code]0[/code] can be used to pause the particles. </member> <member name="sub_emitter" type="NodePath" setter="set_sub_emitter" getter="get_sub_emitter" default="NodePath("")"> - The [NodePath] to the [GPUParticles2D] used for sub-emissions. + Path to another [GPUParticles2D] node that will be used as a subemitter (see [member ParticleProcessMaterial.sub_emitter_mode]). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more. + [b]Note:[/b] When [member sub_emitter] is set, the target [GPUParticles2D] node will no longer emit particles on its own. </member> <member name="texture" type="Texture2D" setter="set_texture" getter="get_texture"> - Particle texture. If [code]null[/code], particles will be squares. + Particle texture. If [code]null[/code], particles will be squares with a size of 1×1 pixels. + [b]Note:[/b] To use a flipbook texture, assign a new [CanvasItemMaterial] to the [GPUParticles2D]'s [member CanvasItem.material] property, then enable [member CanvasItemMaterial.particles_animation] and set [member CanvasItemMaterial.particles_anim_h_frames], [member CanvasItemMaterial.particles_anim_v_frames], and [member CanvasItemMaterial.particles_anim_loop] to match the flipbook texture. </member> <member name="trail_enabled" type="bool" setter="set_trail_enabled" getter="is_trail_enabled" default="false"> If [code]true[/code], enables particle trails using a mesh skinning system. diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index dc7e51b7d7..a982c7e40e 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -61,13 +61,16 @@ </methods> <members> <member name="amount" type="int" setter="set_amount" getter="get_amount" default="8"> - Number of particles to emit. + The number of particles to emit in one emission cycle. The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if [member amount_ratio] is decreased. + [b]Note:[/b] Changing this value will cause the particle system to restart. To avoid this, change [member amount_ratio] instead. </member> <member name="amount_ratio" type="float" setter="set_amount_ratio" getter="get_amount_ratio" default="1.0"> The ratio of particles that should actually be emitted. If set to a value lower than [code]1.0[/code], this will set the amount of emitted particles throughout the lifetime to [code]amount * amount_ratio[/code]. Unlike changing [member amount], changing [member amount_ratio] while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. [member amount_ratio] can be used to create effects that make the number of emitted particles vary over time. - [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. + [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. If you don't intend to change the number of particles emitted while the particles are emitting, make sure [member amount_ratio] is set to [code]1[/code] and change [member amount] to your liking instead. </member> <member name="collision_base_size" type="float" setter="set_collision_base_size" getter="get_collision_base_size" default="0.01"> + The base diameter for particle collision in meters. If particles appear to sink into the ground when colliding, increase this value. If particles appear to float when colliding, decrease this value. Only effective if [member ParticleProcessMaterial.collision_mode] is [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT]. + [b]Note:[/b] Particles always have a spherical collision shape. </member> <member name="draw_order" type="int" setter="set_draw_order" getter="get_draw_order" enum="GPUParticles3D.DrawOrder" default="0"> Particle draw order. Uses [enum DrawOrder] values. @@ -104,13 +107,13 @@ </member> <member name="interp_to_end" type="float" setter="set_interp_to_end" getter="get_interp_to_end" default="0.0"> Causes all the particles in this node to interpolate towards the end of their lifetime. - [b]Note[/b]: This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. + [b]Note:[/b] This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. </member> <member name="interpolate" type="bool" setter="set_interpolate" getter="get_interpolate" default="true"> Enables particle interpolation, which makes the particle movement smoother when their [member fixed_fps] is lower than the screen refresh rate. </member> <member name="lifetime" type="float" setter="set_lifetime" getter="get_lifetime" default="1.0"> - Amount of time each particle will exist. + The amount of time each particle will exist (in seconds). The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. </member> <member name="local_coords" type="bool" setter="set_use_local_coordinates" getter="get_use_local_coordinates" default="false"> If [code]true[/code], particles use the parent node's coordinate space (known as local coordinates). This will cause particles to move and rotate along the [GPUParticles3D] node (and its parents) when it is moved or rotated. If [code]false[/code], particles use global coordinates; they will not move or rotate along the [GPUParticles3D] node (and its parents) when it is moved or rotated. @@ -131,6 +134,8 @@ Speed scaling ratio. A value of [code]0[/code] can be used to pause the particles. </member> <member name="sub_emitter" type="NodePath" setter="set_sub_emitter" getter="get_sub_emitter" default="NodePath("")"> + Path to another [GPUParticles3D] node that will be used as a subemitter (see [member ParticleProcessMaterial.sub_emitter_mode]). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more. + [b]Note:[/b] When [member sub_emitter] is set, the target [GPUParticles3D] node will no longer emit particles on its own. </member> <member name="trail_enabled" type="bool" setter="set_trail_enabled" getter="is_trail_enabled" default="false"> If [code]true[/code], enables particle trails using a mesh skinning system. Designed to work with [RibbonTrailMesh] and [TubeTrailMesh]. @@ -143,8 +148,9 @@ <member name="transform_align" type="int" setter="set_transform_align" getter="get_transform_align" enum="GPUParticles3D.TransformAlign" default="0"> </member> <member name="visibility_aabb" type="AABB" setter="set_visibility_aabb" getter="get_visibility_aabb" default="AABB(-4, -4, -4, 8, 8, 8)"> - The [AABB] that determines the node's region which needs to be visible on screen for the particle system to be active. + The [AABB] that determines the node's region which needs to be visible on screen for the particle system to be active. [member GeometryInstance3D.extra_cull_margin] is added on each of the AABB's axes. Particle collisions and attraction will only occur within this area. Grow the box if particles suddenly appear/disappear when the node enters/exits the screen. The [AABB] can be grown via code or with the [b]Particles → Generate AABB[/b] editor tool. + [b]Note:[/b] [member visibility_aabb] is overridden by [member GeometryInstance3D.custom_aabb] if that property is set to a non-default value. </member> </members> <signals> diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index c59b2944bb..410efd6389 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -214,7 +214,7 @@ <param index="3" name="to_port" type="int" /> <param index="4" name="amount" type="float" /> <description> - Sets the coloration of the connection between [param from_node]'s [param from_port] and [param to_node]'s [param to_port] with the color provided in the [theme_item activity] theme property. + Sets the coloration of the connection between [param from_node]'s [param from_port] and [param to_node]'s [param to_port] with the color provided in the [theme_item activity] theme property. The color is linearly interpolated between the connection color and the activity color using [param amount] as weight. </description> </method> <method name="set_selected"> @@ -408,6 +408,7 @@ </constants> <theme_items> <theme_item name="activity" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> + Color of the connection's activity (see [method set_connection_activity]). </theme_item> <theme_item name="grid_major" data_type="color" type="Color" default="Color(1, 1, 1, 0.2)"> Color of major grid lines. diff --git a/doc/classes/ImmediateMesh.xml b/doc/classes/ImmediateMesh.xml index bde11a850e..7e40d0b4c5 100644 --- a/doc/classes/ImmediateMesh.xml +++ b/doc/classes/ImmediateMesh.xml @@ -15,6 +15,14 @@ mesh.surface_add_vertex(Vector3.ZERO) mesh.surface_end() [/gdscript] + [csharp] + var mesh = new ImmediateMesh(); + mesh.SurfaceBegin(Mesh.PrimitiveType.Triangles); + mesh.SurfaceAddVertex(Vector3.Left); + mesh.SurfaceAddVertex(Vector3.Forward); + mesh.SurfaceAddVertex(Vector3.Zero); + mesh.SurfaceEnd(); + [/csharp] [/codeblocks] [b]Note:[/b] Generating complex geometries with [ImmediateMesh] is highly inefficient. Instead, it is designed to generate simple geometry that changes often. </description> diff --git a/doc/classes/ImporterMesh.xml b/doc/classes/ImporterMesh.xml index 657d5659f8..9bc1bf035e 100644 --- a/doc/classes/ImporterMesh.xml +++ b/doc/classes/ImporterMesh.xml @@ -92,7 +92,7 @@ <return type="Array" /> <param index="0" name="surface_idx" type="int" /> <description> - Returns the arrays for the vertices, normals, uvs, etc. that make up the requested surface. See [method add_surface]. + Returns the arrays for the vertices, normals, UVs, etc. that make up the requested surface. See [method add_surface]. </description> </method> <method name="get_surface_blend_shape_arrays" qualifiers="const"> diff --git a/doc/classes/InputEventKey.xml b/doc/classes/InputEventKey.xml index 5c4dc8e65d..48a6804290 100644 --- a/doc/classes/InputEventKey.xml +++ b/doc/classes/InputEventKey.xml @@ -79,7 +79,25 @@ </member> <member name="physical_keycode" type="int" setter="set_physical_keycode" getter="get_physical_keycode" enum="Key" default="0"> Represents the physical location of a key on the 101/102-key US QWERTY keyboard, which corresponds to one of the [enum Key] constants. - To get a human-readable representation of the [InputEventKey], use [code]OS.get_keycode_string(event.keycode)[/code] where [code]event[/code] is the [InputEventKey]. + To get a human-readable representation of the [InputEventKey], use [method OS.get_keycode_string] in combination with [method DisplayServer.keyboard_get_keycode_from_physical]: + [codeblocks] + [gdscript] + func _input(event): + if event is InputEventKey: + var keycode = DisplayServer.keyboard_get_keycode_from_physical(event.physical_keycode) + print(OS.get_keycode_string(keycode)) + [/gdscript] + [csharp] + public override void _Input(InputEvent @event) + { + if (@event is InputEventKey inputEventKey) + { + var keycode = DisplayServer.KeyboardGetKeycodeFromPhysical(inputEventKey.PhysicalKeycode); + GD.Print(OS.GetKeycodeString(keycode)); + } + } + [/csharp] + [/codeblocks] </member> <member name="pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false"> If [code]true[/code], the key's state is pressed. If [code]false[/code], the key's state is released. diff --git a/doc/classes/InputEventMagnifyGesture.xml b/doc/classes/InputEventMagnifyGesture.xml index bf92155139..627344a136 100644 --- a/doc/classes/InputEventMagnifyGesture.xml +++ b/doc/classes/InputEventMagnifyGesture.xml @@ -5,6 +5,7 @@ </brief_description> <description> Stores the factor of a magnifying touch gesture. This is usually performed when the user pinches the touch screen and used for zooming in/out. + [b]Note:[/b] On Android, this requires the [member ProjectSettings.input_devices/pointing/android/enable_pan_and_scale_gestures] project setting to be enabled. </description> <tutorials> <link title="Using InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link> diff --git a/doc/classes/InputEventPanGesture.xml b/doc/classes/InputEventPanGesture.xml index 9966550c1a..512b2cce51 100644 --- a/doc/classes/InputEventPanGesture.xml +++ b/doc/classes/InputEventPanGesture.xml @@ -5,6 +5,7 @@ </brief_description> <description> Stores information about pan gestures. A pan gesture is performed when the user swipes the touch screen with two fingers. It's typically used for panning/scrolling. + [b]Note:[/b] On Android, this requires the [member ProjectSettings.input_devices/pointing/android/enable_pan_and_scale_gestures] project setting to be enabled. </description> <tutorials> <link title="Using InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link> diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index ebb36ba92b..d0bc7926ca 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -52,7 +52,7 @@ [b]Note:[/b] Only effective for [OmniLight3D] and [SpotLight3D], and only when [member shadow_enabled] is [code]true[/code]. </member> <member name="editor_only" type="bool" setter="set_editor_only" getter="is_editor_only" default="false"> - If [code]true[/code], the light only appears in the editor and will not be visible at runtime. + If [code]true[/code], the light only appears in the editor and will not be visible at runtime. If [code]true[/code], the light will never be baked in [LightmapGI] regardless of its [member light_bake_mode]. </member> <member name="light_angular_distance" type="float" setter="set_param" getter="get_param" default="0.0"> The light's angular size in degrees. Increasing this will make shadows softer at greater distances (also called percentage-closer soft shadows, or PCSS). Only available for [DirectionalLight3D]s. For reference, the Sun from the Earth is approximately [code]0.5[/code]. Increasing this value above [code]0.0[/code] for lights with shadows enabled will have a noticeable performance cost due to PCSS. @@ -203,6 +203,7 @@ </constant> <constant name="BAKE_STATIC" value="1" enum="BakeMode"> Light is taken into account in static baking ([VoxelGI], [LightmapGI], SDFGI ([member Environment.sdfgi_enabled])). The light can be moved around or modified, but its global illumination will not update in real-time. This is suitable for subtle changes (such as flickering torches), but generally not large changes such as toggling a light on and off. + [b]Note:[/b] The light is not baked in [LightmapGI] if [member editor_only] is [code]true[/code]. </constant> <constant name="BAKE_DYNAMIC" value="2" enum="BakeMode"> Light is taken into account in dynamic baking ([VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) only). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to [constant BAKE_STATIC]. This has a greater performance cost compared to [constant BAKE_STATIC]. When using SDFGI, the update speed of dynamic lights is affected by [member ProjectSettings.rendering/global_illumination/sdfgi/frames_to_update_lights]. diff --git a/doc/classes/LightOccluder2D.xml b/doc/classes/LightOccluder2D.xml index 533e87bce9..e42ecd1c49 100644 --- a/doc/classes/LightOccluder2D.xml +++ b/doc/classes/LightOccluder2D.xml @@ -17,6 +17,7 @@ The LightOccluder2D's occluder light mask. The LightOccluder2D will cast shadows only from Light2D(s) that have the same light mask(s). </member> <member name="sdf_collision" type="bool" setter="set_as_sdf_collision" getter="is_set_as_sdf_collision" default="true"> + If enabled, the occluder will be part of a real-time generated signed distance field that can be used in custom shaders. </member> </members> </class> diff --git a/doc/classes/LightmapGI.xml b/doc/classes/LightmapGI.xml index e111251336..ec75d85898 100644 --- a/doc/classes/LightmapGI.xml +++ b/doc/classes/LightmapGI.xml @@ -32,7 +32,7 @@ The strength of denoising step applied to the generated lightmaps. Only effective if [member use_denoiser] is [code]true[/code] and [member ProjectSettings.rendering/lightmapping/denoising/denoiser] is set to JNLM. </member> <member name="directional" type="bool" setter="set_directional" getter="is_directional" default="false"> - If [code]true[/code], bakes lightmaps to contain directional information as spherical harmonics. This results in more realistic lighting appearance, especially with normal mapped materials and for lights that have their direct light baked ([member Light3D.light_bake_mode] set to [constant Light3D.BAKE_STATIC]). The directional information is also used to provide rough reflections for static and dynamic objects. This has a small run-time performance cost as the shader has to perform more work to interpret the direction information from the lightmap. Directional lightmaps also take longer to bake and result in larger file sizes. + If [code]true[/code], bakes lightmaps to contain directional information as spherical harmonics. This results in more realistic lighting appearance, especially with normal mapped materials and for lights that have their direct light baked ([member Light3D.light_bake_mode] set to [constant Light3D.BAKE_STATIC] and with [member Light3D.editor_only] set to [code]false[/code]). The directional information is also used to provide rough reflections for static and dynamic objects. This has a small run-time performance cost as the shader has to perform more work to interpret the direction information from the lightmap. Directional lightmaps also take longer to bake and result in larger file sizes. [b]Note:[/b] The property's name has no relationship with [DirectionalLight3D]. [member directional] works with all light types. </member> <member name="environment_custom_color" type="Color" setter="set_environment_custom_color" getter="get_environment_custom_color"> diff --git a/doc/classes/LightmapGIData.xml b/doc/classes/LightmapGIData.xml index 09c4383829..db6c9e70ca 100644 --- a/doc/classes/LightmapGIData.xml +++ b/doc/classes/LightmapGIData.xml @@ -54,8 +54,12 @@ </method> </methods> <members> - <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture"> + <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture" is_deprecated="true"> The lightmap atlas texture generated by the lightmapper. + [i]Deprecated.[/i] The lightmap atlas can now have multiple textures. See [member lightmap_textures]. + </member> + <member name="lightmap_textures" type="TextureLayered[]" setter="set_lightmap_textures" getter="get_lightmap_textures" default="[]"> + The lightmap atlas textures generated by the lightmapper. </member> </members> </class> diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml index e2aa13403a..e706e3d6e0 100644 --- a/doc/classes/LineEdit.xml +++ b/doc/classes/LineEdit.xml @@ -269,7 +269,7 @@ If [code]true[/code], every character is replaced with the secret character (see [member secret_character]). </member> <member name="secret_character" type="String" setter="set_secret_character" getter="get_secret_character" default=""•""> - The character to use to mask secret input (defaults to "•"). Only a single character can be used as the secret character. + The character to use to mask secret input. Only a single character can be used as the secret character. If it is longer than one character, only the first one will be used. If it is empty, a space will be used instead. </member> <member name="select_all_on_focus" type="bool" setter="set_select_all_on_focus" getter="is_select_all_on_focus" default="false"> If [code]true[/code], the [LineEdit] will select the whole text when it gains focus. diff --git a/doc/classes/Material.xml b/doc/classes/Material.xml index 1118461445..87fa3fd676 100644 --- a/doc/classes/Material.xml +++ b/doc/classes/Material.xml @@ -1,10 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Material" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Abstract base class for applying visual properties to an object, such as color and roughness. + Virtual base class for applying visual properties to an object, such as color and roughness. </brief_description> <description> [Material] is a base resource used for coloring and shading geometry. All materials inherit from it and almost all [VisualInstance3D] derived nodes carry a [Material]. A few flags and parameters are shared between all material types and are configured here. + Importantly, you can inherit from [Material] to create your own custom material type in script or in GDExtension. </description> <tutorials> <link title="3D Material Testers Demo">https://godotengine.org/asset-library/asset/123</link> @@ -14,21 +15,25 @@ <method name="_can_do_next_pass" qualifiers="virtual const"> <return type="bool" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally to determine if [member next_pass] should be shown in the editor or not. </description> </method> <method name="_can_use_render_priority" qualifiers="virtual const"> <return type="bool" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally to determine if [member render_priority] should be shown in the editor or not. </description> </method> <method name="_get_shader_mode" qualifiers="virtual const"> <return type="int" enum="Shader.Mode" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally by various editor tools. </description> </method> <method name="_get_shader_rid" qualifiers="virtual const"> <return type="RID" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally by various editor tools. Used to access the RID of the [Material]'s [Shader]. </description> </method> <method name="create_placeholder" qualifiers="const"> @@ -40,18 +45,20 @@ <method name="inspect_native_shader_code"> <return type="void" /> <description> + Only available when running in the editor. Opens a popup that visualizes the generated shader code, including all variants and internal shader code. </description> </method> </methods> <members> <member name="next_pass" type="Material" setter="set_next_pass" getter="get_next_pass"> Sets the [Material] to be used for the next pass. This renders the object again using a different material. + [b]Note:[/b] [member next_pass] materials are not necessarily drawn immediately after the source [Material]. Draw order is determined by material properties, [member render_priority], and distance to camera. [b]Note:[/b] This only applies to [StandardMaterial3D]s and [ShaderMaterial]s with type "Spatial". </member> <member name="render_priority" type="int" setter="set_render_priority" getter="get_render_priority"> - Sets the render priority for transparent objects in 3D scenes. Higher priority objects will be sorted in front of lower priority objects. + Sets the render priority for objects in 3D scenes. Higher priority objects will be sorted in front of lower priority objects. In other words, all objects with [member render_priority] [code]1[/code] will render before all objects with [member render_priority] [code]0[/code]). [b]Note:[/b] This only applies to [StandardMaterial3D]s and [ShaderMaterial]s with type "Spatial". - [b]Note:[/b] This only applies to sorting of transparent objects. This will not impact how transparent objects are sorted relative to opaque objects. This is because opaque objects are not sorted, while transparent objects are sorted from back to front (subject to priority). + [b]Note:[/b] This will not impact how transparent objects are sorted relative to opaque objects or how dynamic meshes will be sorted relative to other opaque meshes. This is because all transparent objects are drawn after all opaque objects and all dynamic opaque meshes are drawn before other opaque meshes. </member> </members> <constants> diff --git a/doc/classes/Mesh.xml b/doc/classes/Mesh.xml index 6f06628122..2b2dc63a33 100644 --- a/doc/classes/Mesh.xml +++ b/doc/classes/Mesh.xml @@ -366,6 +366,9 @@ <constant name="ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY" value="268435456" enum="ArrayFormat" is_bitfield="true"> Flag used to mark that the mesh intentionally contains no vertex array. </constant> + <constant name="ARRAY_FLAG_COMPRESS_ATTRIBUTES" value="536870912" enum="ArrayFormat" is_bitfield="true"> + Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, UVs). When this form of compression is enabled, vertex positions will be packed into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into an RG16UNORM representing an axis, and a 16-bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32-bit signed floats. When using this compression mode you must use either vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can. + </constant> <constant name="BLEND_SHAPE_MODE_NORMALIZED" value="0" enum="BlendShapeMode"> Blend shapes are normalized. </constant> diff --git a/doc/classes/MultiplayerAPIExtension.xml b/doc/classes/MultiplayerAPIExtension.xml index 4a2d397260..7f6e7951b2 100644 --- a/doc/classes/MultiplayerAPIExtension.xml +++ b/doc/classes/MultiplayerAPIExtension.xml @@ -15,7 +15,7 @@ var base_multiplayer = SceneMultiplayer.new() func _init(): - # Just passthourgh base signals (copied to var to avoid cyclic reference) + # Just passthrough base signals (copied to var to avoid cyclic reference) var cts = connected_to_server var cf = connection_failed var pc = peer_connected @@ -25,13 +25,16 @@ base_multiplayer.peer_connected.connect(func(id): pc.emit(id)) base_multiplayer.peer_disconnected.connect(func(id): pd.emit(id)) + func _poll(): + return base_multiplayer.poll() + # Log RPC being made and forward it to the default multiplayer. - func _rpc(peer: int, object: Object, method: StringName, args: Array) -> int: # Error + func _rpc(peer: int, object: Object, method: StringName, args: Array) -> Error: print("Got RPC for %d: %s::%s(%s)" % [peer, object, method, args]) return base_multiplayer.rpc(peer, object, method, args) # Log configuration add. E.g. root path (nullptr, NodePath), replication (Node, Spawner|Synchronizer), custom. - func _object_configuration_add(object, config: Variant) -> int: # Error + func _object_configuration_add(object, config: Variant) -> Error: if config is MultiplayerSynchronizer: print("Adding synchronization configuration for %s. Synchronizer: %s" % [object, config]) elif config is MultiplayerSpawner: @@ -39,7 +42,7 @@ return base_multiplayer.object_configuration_add(object, config) # Log configuration remove. E.g. root path (nullptr, NodePath), replication (Node, Spawner|Synchronizer), custom. - func _object_configuration_remove(object, config: Variant) -> int: # Error + func _object_configuration_remove(object, config: Variant) -> Error: if config is MultiplayerSynchronizer: print("Removing synchronization configuration for %s. Synchronizer: %s" % [object, config]) elif config is MultiplayerSpawner: diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml index daeb7b0ff6..ec9f679307 100644 --- a/doc/classes/NavigationAgent3D.xml +++ b/doc/classes/NavigationAgent3D.xml @@ -167,6 +167,9 @@ <member name="height" type="float" setter="set_height" getter="get_height" default="1.0"> The height of the avoidance agent. Agents will ignore other agents or obstacles that are above or below their current position + height in 2D avoidance. Does nothing in 3D avoidance which uses radius spheres alone. </member> + <member name="keep_y_velocity" type="bool" setter="set_keep_y_velocity" getter="get_keep_y_velocity" default="true"> + If [code]true[/code], and the agent uses 2D avoidance, it will remember the set y-axis velocity and reapply it after the avoidance step. While 2D avoidance has no y-axis and simulates on a flat plane this setting can help mitigate the most obvious clipping on uneven 3D geometry. + </member> <member name="max_neighbors" type="int" setter="set_max_neighbors" getter="get_max_neighbors" default="10"> The maximum number of neighbors for the agent to consider. </member> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 98b71e32df..f018d9581d 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -1034,7 +1034,7 @@ Notification received every frame when the internal physics process flag is set (see [method set_physics_process_internal]). </constant> <constant name="NOTIFICATION_POST_ENTER_TREE" value="27"> - Notification received when the node is ready, just before [constant NOTIFICATION_READY] is received. Unlike the latter, it's sent every time the node enters tree, instead of only once. + Notification received when the node is ready, just before [constant NOTIFICATION_READY] is received. Unlike the latter, it's sent every time the node enters the tree, instead of only once. </constant> <constant name="NOTIFICATION_DISABLED" value="28"> Notification received when the node is disabled. See [constant PROCESS_MODE_DISABLED]. @@ -1042,9 +1042,6 @@ <constant name="NOTIFICATION_ENABLED" value="29"> Notification received when the node is enabled again after being disabled. See [constant PROCESS_MODE_DISABLED]. </constant> - <constant name="NOTIFICATION_NODE_RECACHE_REQUESTED" value="30"> - Notification received when other nodes in the tree may have been removed/replaced and node pointers may require re-caching. - </constant> <constant name="NOTIFICATION_EDITOR_PRE_SAVE" value="9001"> Notification received right before the scene with the node is saved in the editor. This notification is only sent in the Godot editor and will not occur in exported projects. </constant> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index bb7289cc99..2ffb02096d 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -5,7 +5,7 @@ </brief_description> <description> An advanced [Variant] type. All classes in the engine inherit from Object. Each class may define new properties, methods or signals, which are available to all inheriting classes. For example, a [Sprite2D] instance is able to call [method Node.add_child] because it inherits from [Node]. - You can create new instances, using [code]Object.new()[/code] in GDScript, or [code]new Object[/code] in C#. + You can create new instances, using [code]Object.new()[/code] in GDScript, or [code]new GodotObject[/code] in C#. To delete an Object instance, call [method free]. This is necessary for most classes inheriting Object, because they do not manage memory on their own, and will otherwise cause memory leaks when no longer in use. There are a few classes that perform memory management. For example, [RefCounted] (and by extension [Resource]) deletes itself when no longer referenced, and [Node] deletes its children when freed. Objects can have a [Script] attached to them. Once the [Script] is instantiated, it effectively acts as an extension to the base class, allowing it to define and inherit new properties, methods and signals. Inside a [Script], [method _get_property_list] may be overridden to customize properties in several ways. This allows them to be available to the editor, display as lists of options, sub-divide into groups, save on disk, etc. Scripting languages offer easier ways to customize properties, such as with the [annotation @GDScript.@export] annotation. @@ -159,7 +159,7 @@ <method name="_init" qualifiers="virtual"> <return type="void" /> <description> - Called when the object's script is instantiated, oftentimes after the object is initialized in memory (through [code]Object.new()[/code] in GDScript, or [code]new Object[/code] in C#). It can be also defined to take in parameters. This method is similar to a constructor in most programming languages. + Called when the object's script is instantiated, oftentimes after the object is initialized in memory (through [code]Object.new()[/code] in GDScript, or [code]new GodotObject[/code] in C#). It can be also defined to take in parameters. This method is similar to a constructor in most programming languages. [b]Note:[/b] If [method _init] is defined with [i]required[/i] parameters, the Object with script may only be created directly. If any other means (such as [method PackedScene.instantiate] or [method Node.duplicate]) are used, the script's initialization will fail. </description> </method> @@ -219,6 +219,7 @@ # Storing the value in the fake property. internal_data["fake_property"] = value return true + return false func _get_property_list(): return [ @@ -228,7 +229,7 @@ [csharp] private Godot.Collections.Dictionary _internalData = new Godot.Collections.Dictionary(); - public override void _Set(StringName property, Variant value) + public override bool _Set(StringName property, Variant value) { if (property == "FakeProperty") { diff --git a/doc/classes/PackedVector2Array.xml b/doc/classes/PackedVector2Array.xml index 9f8671f076..0e5bb12d02 100644 --- a/doc/classes/PackedVector2Array.xml +++ b/doc/classes/PackedVector2Array.xml @@ -204,7 +204,9 @@ <return type="PackedVector2Array" /> <param index="0" name="right" type="Transform2D" /> <description> - Transforms (multiplies) all vectors in the array by the [Transform2D] matrix. + Returns a new [PackedVector2Array] with all vectors in this array inversely transformed (multiplied) by the given [Transform2D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]array * transform[/code] is equivalent to [code]transform.inverse() * array[/code]. See [method Transform2D.inverse]. + For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * array[/code] can be used instead. See [method Transform2D.affine_inverse]. </description> </operator> <operator name="operator +"> diff --git a/doc/classes/PackedVector3Array.xml b/doc/classes/PackedVector3Array.xml index 54f65a619b..ce7ae4f396 100644 --- a/doc/classes/PackedVector3Array.xml +++ b/doc/classes/PackedVector3Array.xml @@ -203,7 +203,9 @@ <return type="PackedVector3Array" /> <param index="0" name="right" type="Transform3D" /> <description> - Transforms (multiplies) all vectors in the array by the [Transform3D] matrix. + Returns a new [PackedVector3Array] with all vectors in this array inversely transformed (multiplied) by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]array * transform[/code] is equivalent to [code]transform.inverse() * array[/code]. See [method Transform3D.inverse]. + For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * array[/code] can be used instead. See [method Transform3D.affine_inverse]. </description> </operator> <operator name="operator +"> diff --git a/doc/classes/ParticleProcessMaterial.xml b/doc/classes/ParticleProcessMaterial.xml index b7f55184f0..aa20260849 100644 --- a/doc/classes/ParticleProcessMaterial.xml +++ b/doc/classes/ParticleProcessMaterial.xml @@ -114,7 +114,7 @@ Minimum equivalent of [member anim_speed_max]. </member> <member name="attractor_interaction_enabled" type="bool" setter="set_attractor_interaction_enabled" getter="is_attractor_interaction_enabled" default="true"> - True if the interaction with particle attractors is enabled. + If [code]true[/code], interaction with particle attractors is enabled. In 3D, attraction only occurs within the area defined by the [GPUParticles3D] node's [member GPUParticles3D.visibility_aabb]. </member> <member name="collision_bounce" type="float" setter="set_collision_bounce" getter="get_collision_bounce"> The particles' bounciness. Values range from [code]0[/code] (no bounce) to [code]1[/code] (full bounciness). Only effective if [member collision_mode] is [constant COLLISION_RIGID]. @@ -124,11 +124,11 @@ </member> <member name="collision_mode" type="int" setter="set_collision_mode" getter="get_collision_mode" enum="ParticleProcessMaterial.CollisionMode" default="0"> The particles' collision mode. - [b]Note:[/b] 3D Particles can only collide with [GPUParticlesCollision3D] nodes, not [PhysicsBody3D] nodes. To make particles collide with various objects, you can add [GPUParticlesCollision3D] nodes as children of [PhysicsBody3D] nodes. + [b]Note:[/b] 3D Particles can only collide with [GPUParticlesCollision3D] nodes, not [PhysicsBody3D] nodes. To make particles collide with various objects, you can add [GPUParticlesCollision3D] nodes as children of [PhysicsBody3D] nodes. In 3D, collisions only occur within the area defined by the [GPUParticles3D] node's [member GPUParticles3D.visibility_aabb]. [b]Note:[/b] 2D Particles can only collide with [LightOccluder2D] nodes, not [PhysicsBody2D] nodes. </member> <member name="collision_use_scale" type="bool" setter="set_collision_use_scale" getter="is_collision_using_scale" default="false"> - Should collision take scale into account. + If [code]true[/code], [member GPUParticles3D.collision_base_size] is multiplied by the particle's effective scale (see [member scale_min], [member scale_max], [member scale_curve], and [member scale_over_velocity_curve]). </member> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> Each particle's initial color. If the [GPUParticles2D]'s [code]texture[/code] is defined, it will be multiplied by this color. @@ -316,16 +316,22 @@ Each particle's initial direction range from [code]+spread[/code] to [code]-spread[/code] degrees. </member> <member name="sub_emitter_amount_at_collision" type="int" setter="set_sub_emitter_amount_at_collision" getter="get_sub_emitter_amount_at_collision"> - Sub particle amount on collision. - Maximum amount set in the sub particles emitter. + The amount of particles to spawn from the subemitter node when a collision occurs. When combined with [constant COLLISION_HIDE_ON_CONTACT] on the main particles material, this can be used to achieve effects such as raindrops hitting the ground. + [b]Note:[/b] This value shouldn't exceed [member GPUParticles2D.amount] or [member GPUParticles3D.amount] defined on the [i]subemitter node[/i] (not the main node), relative to the subemitter's particle lifetime. If the number of particles is exceeded, no new particles will spawn from the subemitter until enough particles have expired. </member> <member name="sub_emitter_amount_at_end" type="int" setter="set_sub_emitter_amount_at_end" getter="get_sub_emitter_amount_at_end"> + The amount of particles to spawn from the subemitter node when the particle expires. + [b]Note:[/b] This value shouldn't exceed [member GPUParticles2D.amount] or [member GPUParticles3D.amount] defined on the [i]subemitter node[/i] (not the main node), relative to the subemitter's particle lifetime. If the number of particles is exceeded, no new particles will spawn from the subemitter until enough particles have expired. </member> <member name="sub_emitter_frequency" type="float" setter="set_sub_emitter_frequency" getter="get_sub_emitter_frequency"> + The frequency at which particles should be emitted from the subemitter node. One particle will be spawned every [member sub_emitter_frequency] seconds. + [b]Note:[/b] This value shouldn't exceed [member GPUParticles2D.amount] or [member GPUParticles3D.amount] defined on the [i]subemitter node[/i] (not the main node), relative to the subemitter's particle lifetime. If the number of particles is exceeded, no new particles will spawn from the subemitter until enough particles have expired. </member> <member name="sub_emitter_keep_velocity" type="bool" setter="set_sub_emitter_keep_velocity" getter="get_sub_emitter_keep_velocity" default="false"> + If [code]true[/code], the subemitter inherits the parent particle's velocity when it spawns. </member> <member name="sub_emitter_mode" type="int" setter="set_sub_emitter_mode" getter="get_sub_emitter_mode" enum="ParticleProcessMaterial.SubEmitterMode" default="0"> + The particle subemitter mode (see [member GPUParticles2D.sub_emitter] and [member GPUParticles3D.sub_emitter]). </member> <member name="tangential_accel_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture"> Each particle's tangential acceleration will vary along this [CurveTexture]. @@ -378,6 +384,7 @@ A [CurveTexture] that defines the maximum velocity of a particle during its lifetime. </member> <member name="velocity_pivot" type="Vector3" setter="set_velocity_pivot" getter="get_velocity_pivot" default="Vector3(0, 0, 0)"> + A pivot point used to calculate radial and orbital velocity of particles. </member> </members> <constants> diff --git a/doc/classes/Plane.xml b/doc/classes/Plane.xml index a0da82d1d6..254557b986 100644 --- a/doc/classes/Plane.xml +++ b/doc/classes/Plane.xml @@ -193,6 +193,7 @@ <param index="0" name="right" type="Transform3D" /> <description> Inversely transforms (multiplies) the [Plane] by the given [Transform3D] transformation matrix. + [code]plane * transform[/code] is equivalent to [code]transform.affine_inverse() * plane[/code]. See [method Transform3D.affine_inverse]. </description> </operator> <operator name="operator =="> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 6293fcb309..3f4ec1b677 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -186,7 +186,7 @@ <param index="1" name="submenu" type="String" /> <param index="2" name="id" type="int" default="-1" /> <description> - Adds an item that will act as a submenu of the parent [PopupMenu] node when clicked. The [param submenu] argument is the name of the child [PopupMenu] node that will be shown when the item is clicked. + Adds an item that will act as a submenu of the parent [PopupMenu] node when clicked. The [param submenu] argument must be the name of an existing [PopupMenu] that has been added as a child to this node. This submenu will be shown when the item is clicked, hovered for long enough, or activated using the [code]ui_select[/code] or [code]ui_right[/code] input actions. An [param id] can optionally be provided. If no [param id] is provided, one will be created from the index. </description> </method> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 126f3a88d7..f63eca94e2 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -393,6 +393,13 @@ The base strength of the panning effect for all [AudioStreamPlayer3D] nodes. The panning strength can be further scaled on each Node using [member AudioStreamPlayer3D.panning_strength]. A value of [code]0.0[/code] disables stereo panning entirely, leaving only volume attenuation in place. A value of [code]1.0[/code] completely mutes one of the channels if the sound is located exactly to the left (or right) of the listener. The default value of [code]0.5[/code] is tuned for headphones. When using speakers, you may find lower values to sound better as speakers have a lower stereo separation compared to headphones. </member> + <member name="audio/general/ios/mix_with_others" type="bool" setter="" getter="" default="false"> + Sets the [url=https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616611-mixwithothers]mixWithOthers[/url] option for the AVAudioSession on iOS. This will override the mix behavior, if the category is set to [code]Play and Record[/code], [code]Playback[/code], or [code]Multi Route[/code]. + [code]Ambient[/code] always has this set per default. + </member> + <member name="audio/general/ios/session_category" type="int" setter="" getter="" default="0"> + Sets the [url=https://developer.apple.com/documentation/avfaudio/avaudiosessioncategory]AVAudioSessionCategory[/url] on iOS. Use the [code]Playback[/code] category to get sound output, even if the phone is in silent mode. + </member> <member name="audio/general/text_to_speech" type="bool" setter="" getter="" default="false"> If [code]true[/code], text-to-speech support is enabled, see [method DisplayServer.tts_get_voices] and [method DisplayServer.tts_speak]. [b]Note:[/b] Enabling TTS can cause addition idle CPU usage and interfere with the sleep mode, so consider disabling it if TTS is not used. @@ -562,6 +569,7 @@ </member> <member name="debug/gdscript/warnings/untyped_declaration" type="int" setter="" getter="" default="0"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a variable or parameter has no static type, or if a function has no static return type. + [b]Note:[/b] This warning is recommended together with [member EditorSettings.text_editor/completion/add_type_hints] to help achieve type safety. </member> <member name="debug/gdscript/warnings/unused_local_constant" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a local constant is never used. @@ -821,7 +829,7 @@ </member> <member name="display/window/size/window_width_override" type="int" setter="" getter="" default="0"> On desktop platforms, overrides the game's initial window width. See also [member display/window/size/window_height_override], [member display/window/size/viewport_width] and [member display/window/size/viewport_height]. - [b]Note:[/b] By default, or when set to [code]0[/code], the initial window width is the viewport [member display/window/size/viewport_width]. This setting is ignored on iOS, Android, and Web. + [b]Note:[/b] By default, or when set to [code]0[/code], the initial window width is the [member display/window/size/viewport_width]. This setting is ignored on iOS, Android, and Web. </member> <member name="display/window/stretch/aspect" type="String" setter="" getter="" default=""keep""> </member> @@ -836,6 +844,9 @@ </member> <member name="display/window/stretch/scale_mode" type="String" setter="" getter="" default=""fractional""> The policy to use to determine the final scale factor for 2D elements. This affects how [member display/window/stretch/scale] is applied, in addition to the automatic scale factor determined by [member display/window/stretch/mode]. + [b]"fractional"[/b]: The scale factor will not be modified. + [b]"integer"[/b]: The scale factor will be floored to an integer value, which means that the screen size will always be an integer multiple of the base viewport size. This provides a crisp pixel art appearance. + [b]Note:[/b] When using integer scaling with a stretch mode, resizing the window to be smaller than the base viewport size will clip the contents. Consider preventing that by setting [member Window.min_size] to the same value as the base viewport size defined in [member display/window/size/viewport_width] and [member display/window/size/viewport_height]. </member> <member name="display/window/subwindows/embed_subwindows" type="bool" setter="" getter="" default="true"> If [code]true[/code] subwindows are embedded in the main window. @@ -2201,7 +2212,7 @@ <member name="physics/common/physics_jitter_fix" type="float" setter="" getter="" default="0.5"> Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows smoothing out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. [b]Note:[/b] For best results, when using a custom physics interpolation solution, the physics jitter fix should be disabled by setting [member physics/common/physics_jitter_fix] to [code]0[/code]. - [b]Note:[/b] This property is only read when the project starts. To change the physics FPS at runtime, set [member Engine.physics_jitter_fix] instead. + [b]Note:[/b] This property is only read when the project starts. To change the physics jitter fix at runtime, set [member Engine.physics_jitter_fix] instead. </member> <member name="physics/common/physics_ticks_per_second" type="int" setter="" getter="" default="60"> The number of fixed iterations per second. This controls how often physics simulation and [method Node._physics_process] methods are run. See also [member application/run/max_fps]. @@ -2357,33 +2368,43 @@ <member name="rendering/environment/volumetric_fog/volume_size" type="int" setter="" getter="" default="64"> Base size used to determine size of froxel buffer in the camera X-axis and Y-axis. The final size is scaled by the aspect ratio of the screen, so actual values may differ from what is set. Set a larger size for more detailed fog, set a smaller size for better performance. </member> - <member name="rendering/gl_compatibility/driver" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver" type="String" setter="" getter=""> Sets the driver to be used by the renderer when using the Compatibility renderer. This property can not be edited directly, instead, set the driver using the platform-specific overrides. </member> - <member name="rendering/gl_compatibility/driver.android" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.android" type="String" setter="" getter=""> Android override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.ios" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.ios" type="String" setter="" getter=""> iOS override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.linuxbsd" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.linuxbsd" type="String" setter="" getter=""> LinuxBSD override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.macos" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.macos" type="String" setter="" getter=""> macOS override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.web" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.web" type="String" setter="" getter=""> Web override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.windows" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.windows" type="String" setter="" getter=""> Windows override for [member rendering/gl_compatibility/driver]. </member> <member name="rendering/gl_compatibility/fallback_to_angle" type="bool" setter="" getter="" default="true"> If [code]true[/code], the compatibility renderer will fall back to ANGLE if native OpenGL is not supported or the device is listed in [member rendering/gl_compatibility/force_angle_on_devices]. + [b]Note:[/b] This setting is implemented only on Windows. + </member> + <member name="rendering/gl_compatibility/fallback_to_gles" type="bool" setter="" getter="" default="true"> + If [code]true[/code], the compatibility renderer will fall back to OpenGLES if desktop OpenGL is not supported. + [b]Note:[/b] This setting is implemented only on Linux/X11. + </member> + <member name="rendering/gl_compatibility/fallback_to_native" type="bool" setter="" getter="" default="true"> + If [code]true[/code], the compatibility renderer will fall back to native OpenGL if ANGLE over Metal is not supported. + [b]Note:[/b] This setting is implemented only on macOS. </member> <member name="rendering/gl_compatibility/force_angle_on_devices" type="Array" setter="" getter="" default="[]"> An [Array] of devices which should always use the ANGLE renderer. Each entry is a [Dictionary] with the following keys: [code]vendor[/code] and [code]name[/code]. [code]name[/code] can be set to [code]*[/code] to add all devices with the specified [code]vendor[/code]. + [b]Note:[/b] This setting is implemented only on Windows. </member> <member name="rendering/gl_compatibility/item_buffer_size" type="int" setter="" getter="" default="16384"> Maximum number of canvas items commands that can be drawn in a single viewport update. If more render commands are issued they will be ignored. Decreasing this limit may improve performance on bandwidth limited devices. Increase this limit if you find that not all objects are being drawn in a frame. @@ -2594,22 +2615,22 @@ <member name="rendering/renderer/rendering_method.web" type="String" setter="" getter="" default=""gl_compatibility""> Override for [member rendering/renderer/rendering_method] on web. </member> - <member name="rendering/rendering_device/driver" type="String" setter="" getter="" default=""vulkan""> + <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. </member> - <member name="rendering/rendering_device/driver.android" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.android" type="String" setter="" getter=""> Android override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.ios" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.ios" type="String" setter="" getter=""> iOS override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.linuxbsd" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.linuxbsd" type="String" setter="" getter=""> LinuxBSD override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.macos" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.macos" type="String" setter="" getter=""> macOS override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.windows" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.windows" type="String" setter="" getter=""> Windows override for [member rendering/rendering_device/driver]. </member> <member name="rendering/rendering_device/pipeline_cache/save_chunk_size_mb" type="float" setter="" getter="" default="3.0"> @@ -2677,7 +2698,6 @@ Affects the final texture sharpness by reading from a lower or higher mipmap (also called "texture LOD bias"). Negative values make mipmapped textures sharper but grainier when viewed at a distance, while positive values make mipmapped textures blurrier (even when up close). Enabling temporal antialiasing ([member rendering/anti_aliasing/quality/use_taa]) will automatically apply a [code]-0.5[/code] offset to this value, while enabling FXAA ([member rendering/anti_aliasing/quality/screen_space_aa]) will automatically apply a [code]-0.25[/code] offset to this value. If both TAA and FXAA are enabled at the same time, an offset of [code]-0.75[/code] is applied to this value. [b]Note:[/b] If [member rendering/scaling_3d/scale] is lower than [code]1.0[/code] (exclusive), [member rendering/textures/default_filters/texture_mipmap_bias] is used to adjust the automatic mipmap bias which is calculated internally based on the scale factor. The formula for this is [code]log2(scaling_3d_scale) + mipmap_bias[/code]. - [b]Note:[/b] This property is only read when the project starts. To change the mipmap LOD bias at run-time, set [member Viewport.texture_mipmap_bias] instead. </member> <member name="rendering/textures/default_filters/use_nearest_mipmap_filter" type="bool" setter="" getter="" default="false"> If [code]true[/code], uses nearest-neighbor mipmap filtering when using mipmaps (also called "bilinear filtering"), which will result in visible seams appearing between mipmap stages. This may increase performance in mobile as less memory bandwidth is used. If [code]false[/code], linear mipmap filtering (also called "trilinear filtering") is used. diff --git a/doc/classes/RandomNumberGenerator.xml b/doc/classes/RandomNumberGenerator.xml index 383988360f..54f18a1ab4 100644 --- a/doc/classes/RandomNumberGenerator.xml +++ b/doc/classes/RandomNumberGenerator.xml @@ -56,7 +56,7 @@ <method name="randomize"> <return type="void" /> <description> - Setups a time-based seed to for this [RandomNumberGenerator] instance. Unlike the [@GlobalScope] random number generation functions, different [RandomNumberGenerator] instances can use different seeds. + Sets up a time-based seed for this [RandomNumberGenerator] instance. Unlike the [@GlobalScope] random number generation functions, different [RandomNumberGenerator] instances can use different seeds. </description> </method> </methods> diff --git a/doc/classes/Rect2.xml b/doc/classes/Rect2.xml index 4f17e3cf2d..0471d73749 100644 --- a/doc/classes/Rect2.xml +++ b/doc/classes/Rect2.xml @@ -237,7 +237,9 @@ <return type="Rect2" /> <param index="0" name="right" type="Transform2D" /> <description> - Inversely transforms (multiplies) the [Rect2] by the given [Transform2D] transformation matrix. + Inversely transforms (multiplies) the [Rect2] by the given [Transform2D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]rect * transform[/code] is equivalent to [code]transform.inverse() * rect[/code]. See [method Transform2D.inverse]. + For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * rect[/code] can be used instead. See [method Transform2D.affine_inverse]. </description> </operator> <operator name="operator =="> diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index b35eb89d19..20faa70226 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -706,7 +706,7 @@ <param index="5" name="layer_count" type="int" /> <param index="6" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Clears the specified [param texture] by replacing all of its pixels with the specified [param color]. [param base_mipmap] and [param mipmap_count] determine which mipmaps of the texture are affected by this clear operation, while [param base_layer] and [param layer_count] determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), [param base_layer] and [param layer_count] must both be [code]0[/code]. + Clears the specified [param texture] by replacing all of its pixels with the specified [param color]. [param base_mipmap] and [param mipmap_count] determine which mipmaps of the texture are affected by this clear operation, while [param base_layer] and [param layer_count] determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), [param base_layer] must be [code]0[/code] and [param layer_count] must be [code]1[/code]. [b]Note:[/b] [param texture] can't be cleared while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to clear this texture. </description> </method> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index dd279206ab..e5409a6e8a 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -4226,7 +4226,7 @@ Flag used to mark that the mesh does not have a vertex array and instead will infer vertex positions in the shader using indices and other information. </constant> <constant name="ARRAY_FLAG_COMPRESS_ATTRIBUTES" value="536870912" enum="ArrayFormat" is_bitfield="true"> - Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, uvs). When this form of compression is enabled, vertex positions will be packed into into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into a RG16UNORM representing an axis, and an 16 bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32 bit signed floats. When using this compression mode you must either use vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can. + Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, UVs). When this form of compression is enabled, vertex positions will be packed into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into an RG16UNORM representing an axis, and a 16-bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32-bit signed floats. When using this compression mode you must use either vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can. </constant> <constant name="ARRAY_FLAG_FORMAT_VERSION_BASE" value="35" enum="ArrayFormat" is_bitfield="true"> Flag used to mark the start of the bits used to store the mesh version. diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 75c258253d..c8146bb48f 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -92,6 +92,7 @@ </member> <member name="resource_name" type="String" setter="set_name" getter="get_name" default=""""> An optional name for this resource. When defined, its value is displayed to represent the resource in the Inspector dock. For built-in scripts, the name is displayed as part of the tab name in the script editor. + [b]Note:[/b] Some resource formats do not support resource names. You can still set the name in the editor or via code, but it will be lost when the resource is reloaded. For example, only built-in scripts can have a resource name, while scripts stored in separate files cannot. </member> <member name="resource_path" type="String" setter="set_path" getter="get_path" default=""""> The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the [PackedScene]'s filepath, followed by a unique identifier. diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 405d189c54..c9a48e46b2 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -764,10 +764,10 @@ The vertical separation of elements in a table. </theme_item> <theme_item name="text_highlight_h_padding" data_type="constant" type="int" default="3"> - The horizontal padding around a highlighting and background color box. + The horizontal padding around boxes drawn by the [code][fgcolor][/code] and [code][bgcolor][/code] tags. This does not affect the appearance of text selection. </theme_item> <theme_item name="text_highlight_v_padding" data_type="constant" type="int" default="3"> - The vertical padding around a highlighting and background color box. + The vertical padding around boxes drawn by the [code][fgcolor][/code] and [code][bgcolor][/code] tags. This does not affect the appearance of text selection. </theme_item> <theme_item name="bold_font" data_type="font" type="Font"> The font used for bold text. diff --git a/doc/classes/ScrollBar.xml b/doc/classes/ScrollBar.xml index e8d2753a9a..4ee05632a5 100644 --- a/doc/classes/ScrollBar.xml +++ b/doc/classes/ScrollBar.xml @@ -49,8 +49,6 @@ <theme_item name="grabber_pressed" data_type="style" type="StyleBox"> Used when the grabber is being dragged. </theme_item> - <theme_item name="hscroll" data_type="style" type="StyleBox"> - </theme_item> <theme_item name="scroll" data_type="style" type="StyleBox"> Used as background of this [ScrollBar]. </theme_item> diff --git a/doc/classes/ShapeCast2D.xml b/doc/classes/ShapeCast2D.xml index a04ffe3881..d71c9ce13a 100644 --- a/doc/classes/ShapeCast2D.xml +++ b/doc/classes/ShapeCast2D.xml @@ -34,7 +34,7 @@ <method name="force_shapecast_update"> <return type="void" /> <description> - Updates the collision information for the shape. Use this method to update the collision information immediately instead of waiting for the next [code]_physics_process[/code] call, for example if the shape or its parent has changed state. + Updates the collision information for the shape immediately, without waiting for the next [code]_physics_process[/code] call. Use this method, for example, when the shape or its parent has changed state. [b]Note:[/b] [code]enabled == true[/code] is not required for this to work. </description> </method> @@ -130,10 +130,10 @@ </methods> <members> <member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false"> - If [code]true[/code], collision with [Area2D]s will be reported. + If [code]true[/code], collisions with [Area2D]s will be reported. </member> <member name="collide_with_bodies" type="bool" setter="set_collide_with_bodies" getter="is_collide_with_bodies_enabled" default="true"> - If [code]true[/code], collision with [PhysicsBody2D]s will be reported. + If [code]true[/code], collisions with [PhysicsBody2D]s will be reported. </member> <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1"> The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. diff --git a/doc/classes/ShapeCast3D.xml b/doc/classes/ShapeCast3D.xml index ce72944098..e189628f4c 100644 --- a/doc/classes/ShapeCast3D.xml +++ b/doc/classes/ShapeCast3D.xml @@ -34,7 +34,7 @@ <method name="force_shapecast_update"> <return type="void" /> <description> - Updates the collision information for the shape. Use this method to update the collision information immediately instead of waiting for the next [code]_physics_process[/code] call, for example if the shape or its parent has changed state. + Updates the collision information for the shape immediately, without waiting for the next [code]_physics_process[/code] call. Use this method, for example, when the shape or its parent has changed state. [b]Note:[/b] [code]enabled == true[/code] is not required for this to work. </description> </method> @@ -137,10 +137,10 @@ </methods> <members> <member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false"> - If [code]true[/code], collision with [Area3D]s will be reported. + If [code]true[/code], collisions with [Area3D]s will be reported. </member> <member name="collide_with_bodies" type="bool" setter="set_collide_with_bodies" getter="is_collide_with_bodies_enabled" default="true"> - If [code]true[/code], collision with [PhysicsBody3D]s will be reported. + If [code]true[/code], collisions with [PhysicsBody3D]s will be reported. </member> <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1"> The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See [url=$DOCS_URL/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information. diff --git a/doc/classes/TabBar.xml b/doc/classes/TabBar.xml index 9b462b9f50..165b187710 100644 --- a/doc/classes/TabBar.xml +++ b/doc/classes/TabBar.xml @@ -317,7 +317,7 @@ <signal name="tab_selected"> <param index="0" name="tab" type="int" /> <description> - Emitted when a tab is selected via click or script, even if it is the current tab. + Emitted when a tab is selected via click, directional input, or script, even if it is the current tab. </description> </signal> </signals> diff --git a/doc/classes/TabContainer.xml b/doc/classes/TabContainer.xml index b08e075a23..b3a9264569 100644 --- a/doc/classes/TabContainer.xml +++ b/doc/classes/TabContainer.xml @@ -243,7 +243,7 @@ <signal name="tab_selected"> <param index="0" name="tab" type="int" /> <description> - Emitted when a tab is selected, even if it is the current tab. + Emitted when a tab is selected via click, directional input, or script, even if it is the current tab. </description> </signal> </signals> diff --git a/doc/classes/Time.xml b/doc/classes/Time.xml index 9dc567562a..79c332327f 100644 --- a/doc/classes/Time.xml +++ b/doc/classes/Time.xml @@ -152,7 +152,9 @@ <method name="get_time_zone_from_system" qualifiers="const"> <return type="Dictionary" /> <description> - Returns the current time zone as a dictionary of keys: [code]bias[/code] and [code]name[/code]. The [code]bias[/code] value is the offset from UTC in minutes, since not all time zones are multiples of an hour from UTC. + Returns the current time zone as a dictionary of keys: [code]bias[/code] and [code]name[/code]. + - [code]bias[/code] is the offset from UTC in minutes, since not all time zones are multiples of an hour from UTC. + - [code]name[/code] is the localized name of the time zone, according to the OS locale settings of the current user. </description> </method> <method name="get_unix_time_from_datetime_dict" qualifiers="const"> diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml index abb81b95cb..aee70f6b59 100644 --- a/doc/classes/Transform2D.xml +++ b/doc/classes/Transform2D.xml @@ -59,7 +59,7 @@ <method name="affine_inverse" qualifiers="const"> <return type="Transform2D" /> <description> - Returns the inverse of the transform, under the assumption that the transformation is composed of rotation, scaling and translation. + Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant). </description> </method> <method name="basis_xform" qualifiers="const"> @@ -67,15 +67,17 @@ <param index="0" name="v" type="Vector2" /> <description> Returns a vector transformed (multiplied) by the basis matrix. - This method does not account for translation (the origin vector). + This method does not account for translation (the [member origin] vector). </description> </method> <method name="basis_xform_inv" qualifiers="const"> <return type="Vector2" /> <param index="0" name="v" type="Vector2" /> <description> - Returns a vector transformed (multiplied) by the inverse basis matrix. - This method does not account for translation (the origin vector). + Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + This method does not account for translation (the [member origin] vector). + [code]transform.basis_xform_inv(vector)[/code] is equivalent to [code]transform.inverse().basis_xform(vector)[/code]. See [method inverse]. + For non-orthonormal transforms (e.g. with scaling) [code]transform.affine_inverse().basis_xform(vector)[/code] can be used instead. See [method affine_inverse]. </description> </method> <method name="determinant" qualifiers="const"> @@ -120,7 +122,7 @@ <method name="inverse" qualifiers="const"> <return type="Transform2D" /> <description> - Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use [method affine_inverse] for transforms with scaling). + Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling). </description> </method> <method name="is_conformal" qualifiers="const"> @@ -274,14 +276,14 @@ <return type="Transform2D" /> <param index="0" name="right" type="float" /> <description> - This operator multiplies all components of the [Transform2D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. </description> </operator> <operator name="operator *"> <return type="Transform2D" /> <param index="0" name="right" type="int" /> <description> - This operator multiplies all components of the [Transform2D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. </description> </operator> <operator name="operator =="> diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index c96be5124e..85da629d70 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -59,7 +59,7 @@ <method name="affine_inverse" qualifiers="const"> <return type="Transform3D" /> <description> - Returns the inverse of the transform, under the assumption that the transformation is composed of rotation, scaling and translation. + Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant). </description> </method> <method name="interpolate_with" qualifiers="const"> @@ -73,7 +73,7 @@ <method name="inverse" qualifiers="const"> <return type="Transform3D" /> <description> - Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use [method affine_inverse] for transforms with scaling). + Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling). </description> </method> <method name="is_equal_approx" qualifiers="const"> @@ -235,14 +235,14 @@ <return type="Transform3D" /> <param index="0" name="right" type="float" /> <description> - This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly. </description> </operator> <operator name="operator *"> <return type="Transform3D" /> <param index="0" name="right" type="int" /> <description> - This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly. </description> </operator> <operator name="operator =="> diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml index fdaaf239f8..3fa7bb46fc 100644 --- a/doc/classes/Vector2.xml +++ b/doc/classes/Vector2.xml @@ -419,7 +419,9 @@ <return type="Vector2" /> <param index="0" name="right" type="Transform2D" /> <description> - Inversely transforms (multiplies) the [Vector2] by the given [Transform2D] transformation matrix. + Inversely transforms (multiplies) the [Vector2] by the given [Transform2D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]vector * transform[/code] is equivalent to [code]transform.inverse() * vector[/code]. See [method Transform2D.inverse]. + For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * vector[/code] can be used instead. See [method Transform2D.affine_inverse]. </description> </operator> <operator name="operator *"> diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml index 92fbdf6850..83a8c6af73 100644 --- a/doc/classes/Vector3.xml +++ b/doc/classes/Vector3.xml @@ -442,7 +442,9 @@ <return type="Vector3" /> <param index="0" name="right" type="Basis" /> <description> - Inversely transforms (multiplies) the [Vector3] by the given [Basis] matrix. + Inversely transforms (multiplies) the [Vector3] by the given [Basis] matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]vector * basis[/code] is equivalent to [code]basis.transposed() * vector[/code]. See [method Basis.transposed]. + For transforming by inverse of a non-orthonormal basis (e.g. with scaling) [code]basis.inverse() * vector[/code] can be used instead. See [method Basis.inverse]. </description> </operator> <operator name="operator *"> @@ -450,13 +452,16 @@ <param index="0" name="right" type="Quaternion" /> <description> Inversely transforms (multiplies) the [Vector3] by the given [Quaternion]. + [code]vector * quaternion[/code] is equivalent to [code]quaternion.inverse() * vector[/code]. See [method Quaternion.inverse]. </description> </operator> <operator name="operator *"> <return type="Vector3" /> <param index="0" name="right" type="Transform3D" /> <description> - Inversely transforms (multiplies) the [Vector3] by the given [Transform3D] transformation matrix. + Inversely transforms (multiplies) the [Vector3] by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + [code]vector * transform[/code] is equivalent to [code]transform.inverse() * vector[/code]. See [method Transform3D.inverse]. + For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * vector[/code] can be used instead. See [method Transform3D.affine_inverse]. </description> </operator> <operator name="operator *"> diff --git a/doc/classes/Vector4.xml b/doc/classes/Vector4.xml index e5ad5631e8..c5503a9357 100644 --- a/doc/classes/Vector4.xml +++ b/doc/classes/Vector4.xml @@ -280,7 +280,8 @@ <return type="Vector4" /> <param index="0" name="right" type="Projection" /> <description> - Inversely transforms (multiplies) the [Vector4] by the given [Projection] matrix. + Transforms (multiplies) the [Vector4] by the transpose of the given [Projection] matrix. + For transforming by inverse of a projection [code]projection.inverse() * vector[/code] can be used instead. See [method Projection.inverse]. </description> </operator> <operator name="operator *"> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 0a3ecef39b..1b5f7148ac 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -258,11 +258,8 @@ <member name="debug_draw" type="int" setter="set_debug_draw" getter="get_debug_draw" enum="Viewport.DebugDraw" default="0"> The overlay mode for test rendered geometry in debug purposes. </member> - <member name="disable_2d" type="bool" setter="set_disable_2d" getter="is_2d_disabled" default="false"> - If [code]true[/code], disables 2D rendering while keeping 3D rendering. See also [member disable_3d]. - </member> <member name="disable_3d" type="bool" setter="set_disable_3d" getter="is_3d_disabled" default="false"> - If [code]true[/code], disables 3D rendering while keeping 2D rendering. See also [member disable_2d]. + Disable 3D rendering (but keep 2D rendering). </member> <member name="fsr_sharpness" type="float" setter="set_fsr_sharpness" getter="get_fsr_sharpness" default="0.2"> Determines how sharp the upscaled image will be when using the FSR upscaling mode. Sharpness halves with every whole number. Values go from 0.0 (sharpest) to 2.0. Values above 2.0 won't make a visible difference. diff --git a/doc/classes/VisibleOnScreenEnabler2D.xml b/doc/classes/VisibleOnScreenEnabler2D.xml index 9f8b07261e..e9017a389b 100644 --- a/doc/classes/VisibleOnScreenEnabler2D.xml +++ b/doc/classes/VisibleOnScreenEnabler2D.xml @@ -1,19 +1,21 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="VisibleOnScreenEnabler2D" inherits="VisibleOnScreenNotifier2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Automatically disables another node if not visible on screen. + A rectangular region of 2D space that, when visible on screen, enables a target node. </brief_description> <description> - VisibleOnScreenEnabler2D detects when it is visible on screen (just like [VisibleOnScreenNotifier2D]) and automatically enables or disables the target node. The target node is disabled when [VisibleOnScreenEnabler2D] is not visible on screen (including when [member CanvasItem.visible] is [code]false[/code]), and enabled when the enabler is visible. The disabling is achieved by changing [member Node.process_mode]. + [VisibleOnScreenEnabler2D] contains a rectangular region of 2D space and a target node. The target node will be automatically enabled (via its [member Node.process_mode] property) when any part of this region becomes visible on the screen, and automatically disabled otherwise. This can for example be used to activate enemies only when the player approaches them. + See [VisibleOnScreenNotifier2D] if you only want to be notified when the region is visible on screen. + [b]Note:[/b] [VisibleOnScreenEnabler2D] uses the render culling code to determine whether it's visible on screen, so it won't function unless [member CanvasItem.visible] is set to [code]true[/code]. </description> <tutorials> </tutorials> <members> <member name="enable_mode" type="int" setter="set_enable_mode" getter="get_enable_mode" enum="VisibleOnScreenEnabler2D.EnableMode" default="0"> - Determines how the node is enabled. Corresponds to [enum Node.ProcessMode]. Disabled node uses [constant Node.PROCESS_MODE_DISABLED]. + Determines how the target node is enabled. Corresponds to [enum Node.ProcessMode]. When the node is disabled, it always uses [constant Node.PROCESS_MODE_DISABLED]. </member> <member name="enable_node_path" type="NodePath" setter="set_enable_node_path" getter="get_enable_node_path" default="NodePath("..")"> - The path to the target node, relative to the [VisibleOnScreenEnabler2D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler2D] is inside scene tree) and every time the [VisibleOnScreenEnabler2D] enters the scene tree. If the path is invalid, nothing will happen. + The path to the target node, relative to the [VisibleOnScreenEnabler2D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler2D] is inside the scene tree) and every time the [VisibleOnScreenEnabler2D] enters the scene tree. If the path is invalid, an error will be printed in the editor and no node will be affected. </member> </members> <constants> diff --git a/doc/classes/VisibleOnScreenEnabler3D.xml b/doc/classes/VisibleOnScreenEnabler3D.xml index 1808953fcc..a26a47ac92 100644 --- a/doc/classes/VisibleOnScreenEnabler3D.xml +++ b/doc/classes/VisibleOnScreenEnabler3D.xml @@ -1,28 +1,32 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="VisibleOnScreenEnabler3D" inherits="VisibleOnScreenNotifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Enables certain nodes only when approximately visible. + A box-shaped region of 3D space that, when visible on screen, enables a target node. </brief_description> <description> - The VisibleOnScreenEnabler3D will disable [RigidBody3D] and [AnimationPlayer] nodes when they are not visible. It will only affect other nodes within the same scene as the VisibleOnScreenEnabler3D itself. - If you just want to receive notifications, use [VisibleOnScreenNotifier3D] instead. - [b]Note:[/b] VisibleOnScreenEnabler3D uses an approximate heuristic for performance reasons. It doesn't take walls and other occlusion into account. The heuristic is an implementation detail and may change in future versions. If you need precise visibility checking, use another method such as adding an [Area3D] node as a child of a [Camera3D] node and/or [method Vector3.dot]. - [b]Note:[/b] VisibleOnScreenEnabler3D will not affect nodes added after scene initialization. + [VisibleOnScreenEnabler3D] contains a box-shaped region of 3D space and a target node. The target node will be automatically enabled (via its [member Node.process_mode] property) when any part of this region becomes visible on the screen, and automatically disabled otherwise. This can for example be used to activate enemies only when the player approaches them. + See [VisibleOnScreenNotifier3D] if you only want to be notified when the region is visible on screen. + [b]Note:[/b] [VisibleOnScreenEnabler3D] uses an approximate heuristic that doesn't take walls and other occlusion into account, unless occlusion culling is used. It also won't function unless [member Node3D.visible] is set to [code]true[/code]. </description> <tutorials> </tutorials> <members> <member name="enable_mode" type="int" setter="set_enable_mode" getter="get_enable_mode" enum="VisibleOnScreenEnabler3D.EnableMode" default="0"> + Determines how the target node is enabled. Corresponds to [enum Node.ProcessMode]. When the node is disabled, it always uses [constant Node.PROCESS_MODE_DISABLED]. </member> <member name="enable_node_path" type="NodePath" setter="set_enable_node_path" getter="get_enable_node_path" default="NodePath("..")"> + The path to the target node, relative to the [VisibleOnScreenEnabler3D]. The target node is cached; it's only assigned when setting this property (if the [VisibleOnScreenEnabler3D] is inside the scene tree) and every time the [VisibleOnScreenEnabler3D] enters the scene tree. If the path is invalid, an error will be printed in the editor and no node will be affected. </member> </members> <constants> <constant name="ENABLE_MODE_INHERIT" value="0" enum="EnableMode"> + Corresponds to [constant Node.PROCESS_MODE_INHERIT]. </constant> <constant name="ENABLE_MODE_ALWAYS" value="1" enum="EnableMode"> + Corresponds to [constant Node.PROCESS_MODE_ALWAYS]. </constant> <constant name="ENABLE_MODE_WHEN_PAUSED" value="2" enum="EnableMode"> + Corresponds to [constant Node.PROCESS_MODE_WHEN_PAUSED]. </constant> </constants> </class> diff --git a/doc/classes/VisibleOnScreenNotifier2D.xml b/doc/classes/VisibleOnScreenNotifier2D.xml index dc36e25003..9d22bf6cff 100644 --- a/doc/classes/VisibleOnScreenNotifier2D.xml +++ b/doc/classes/VisibleOnScreenNotifier2D.xml @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="VisibleOnScreenNotifier2D" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Detects when the node extents are visible on screen. + A rectangular region of 2D space that detects whether it is visible on screen. </brief_description> <description> - The VisibleOnScreenNotifier2D detects when it is visible on the screen. It also notifies when its bounding rectangle enters or exits the screen or a viewport. - If you want nodes to be disabled automatically when they exit the screen, use [VisibleOnScreenEnabler2D] instead. - [b]Note:[/b] VisibleOnScreenNotifier2D uses the render culling code to determine whether it's visible on screen, which also means that its [member CanvasItem.visible] must be [code]true[/code] to work correctly. + [VisibleOnScreenEnabler2D] represents a rectangular region of 2D space. When any part of this region becomes visible on screen or in a viewport, it will emit a [signal screen_entered] signal, and likewise it will emit a [signal screen_exited] signal when no part of it remains visible. + If you want a node to be enabled automatically when this region is visible on screen, use [VisibleOnScreenEnabler2D]. + [b]Note:[/b] [VisibleOnScreenNotifier2D] uses the render culling code to determine whether it's visible on screen, so it won't function unless [member CanvasItem.visible] is set to [code]true[/code]. </description> <tutorials> <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link> @@ -16,7 +16,7 @@ <return type="bool" /> <description> If [code]true[/code], the bounding rectangle is on the screen. - [b]Note:[/b] It takes one frame for the node's visibility to be assessed once added to the scene tree, so this method will return [code]false[/code] right after it is instantiated, even if it will be on screen in the draw pass. + [b]Note:[/b] It takes one frame for the [VisibleOnScreenNotifier2D]'s visibility to be determined once added to the scene tree, so this method will always return [code]false[/code] right after it is instantiated, before the draw pass. </description> </method> </methods> diff --git a/doc/classes/VisibleOnScreenNotifier3D.xml b/doc/classes/VisibleOnScreenNotifier3D.xml index ba1fa763d3..38d55cd331 100644 --- a/doc/classes/VisibleOnScreenNotifier3D.xml +++ b/doc/classes/VisibleOnScreenNotifier3D.xml @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="VisibleOnScreenNotifier3D" inherits="VisualInstance3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Detects approximately when the node is visible on screen. + A box-shaped region of 3D space that detects whether it is visible on screen. </brief_description> <description> - The VisibleOnScreenNotifier3D detects when it is visible on the screen. It also notifies when its bounding rectangle enters or exits the screen or a [Camera3D]'s view. - If you want nodes to be disabled automatically when they exit the screen, use [VisibleOnScreenEnabler3D] instead. - [b]Note:[/b] VisibleOnScreenNotifier3D uses the render culling code to determine whether it's visible on screen, which also means that its [member Node3D.visible] must be [code]true[/code] to work correctly. + [VisibleOnScreenEnabler3D] represents a box-shaped region of 3D space. When any part of this region becomes visible on screen or in a [Camera3D]'s view, it will emit a [signal screen_entered] signal, and likewise it will emit a [signal screen_exited] signal when no part of it remains visible. + If you want a node to be enabled automatically when this region is visible on screen, use [VisibleOnScreenEnabler3D]. + [b]Note:[/b] [VisibleOnScreenNotifier3D] uses an approximate heuristic that doesn't take walls and other occlusion into account, unless occlusion culling is used. It also won't function unless [member Node3D.visible] is set to [code]true[/code]. </description> <tutorials> </tutorials> @@ -14,25 +14,25 @@ <method name="is_on_screen" qualifiers="const"> <return type="bool" /> <description> - If [code]true[/code], the bounding box is on the screen. - [b]Note:[/b] It takes one frame for the node's visibility to be assessed once added to the scene tree, so this method will return [code]false[/code] right after it is instantiated, even if it will be on screen in the draw pass. + Returns [code]true[/code] if the bounding box is on the screen. + [b]Note:[/b] It takes one frame for the [VisibleOnScreenNotifier3D]'s visibility to be assessed once added to the scene tree, so this method will always return [code]false[/code] right after it is instantiated. </description> </method> </methods> <members> <member name="aabb" type="AABB" setter="set_aabb" getter="get_aabb" default="AABB(-1, -1, -1, 2, 2, 2)"> - The VisibleOnScreenNotifier3D's bounding box. + The [VisibleOnScreenNotifier3D]'s bounding box. </member> </members> <signals> <signal name="screen_entered"> <description> - Emitted when the VisibleOnScreenNotifier3D enters the screen. + Emitted when the [VisibleOnScreenNotifier3D] enters the screen. </description> </signal> <signal name="screen_exited"> <description> - Emitted when the VisibleOnScreenNotifier3D exits the screen. + Emitted when the [VisibleOnScreenNotifier3D] exits the screen. </description> </signal> </signals> |