From fe0d415948f08327ca1fb26c69e69e7c49faad50 Mon Sep 17 00:00:00 2001 From: Godot Organization Date: Sat, 4 Nov 2023 03:21:07 +0000 Subject: [PATCH] classref: Sync with current master branch (5ee9831) --- classes/class_@globalscope.rst | 6 +- classes/class_aabb.rst | 6 +- classes/class_animation.rst | 2 +- .../class_audiostreamgeneratorplayback.rst | 4 +- classes/class_basematerial3d.rst | 2 +- classes/class_button.rst | 4 +- classes/class_concavepolygonshape2d.rst | 2 +- classes/class_concavepolygonshape3d.rst | 2 +- classes/class_control.rst | 8 +- classes/class_dictionary.rst | 42 +++++++ classes/class_gpuparticles2d.rst | 22 ++-- classes/class_gpuparticles3d.rst | 22 ++-- classes/class_graphedit.rst | 6 +- classes/class_immediatemesh.rst | 9 ++ classes/class_importermesh.rst | 2 +- classes/class_light3d.rst | 4 +- classes/class_lightmapgi.rst | 2 +- classes/class_lightmapgidata.rst | 27 ++++- classes/class_lightoccluder2d.rst | 4 +- classes/class_lineedit.rst | 2 +- classes/class_mesh.rst | 8 ++ classes/class_multiplayerapiextension.rst | 11 +- classes/class_navigationagent3d.rst | 19 +++ classes/class_node.rst | 2 +- classes/class_object.rst | 7 +- classes/class_packedvector2array.rst | 6 +- classes/class_packedvector3array.rst | 6 +- classes/class_particleprocessmaterial.rst | 30 ++--- classes/class_plane.rst | 2 + classes/class_popupmenu.rst | 2 +- classes/class_projectsettings.rst | 114 +++++++++++++----- classes/class_randomnumbergenerator.rst | 2 +- classes/class_rect2.rst | 6 +- classes/class_renderingdevice.rst | 2 +- classes/class_renderingserver.rst | 2 +- classes/class_resource.rst | 2 + classes/class_richtextlabel.rst | 4 +- classes/class_scrollbar.rst | 16 --- classes/class_tabbar.rst | 2 +- classes/class_tabcontainer.rst | 2 +- classes/class_time.rst | 6 +- classes/class_transform2d.rst | 18 +-- classes/class_transform3d.rst | 8 +- classes/class_vector2.rst | 6 +- classes/class_vector3.rst | 14 ++- classes/class_vector4.rst | 4 +- classes/class_viewport.rst | 21 +--- classes/class_visibleonscreenenabler2d.rst | 12 +- classes/class_visibleonscreenenabler3d.rst | 24 ++-- classes/class_visibleonscreennotifier2d.rst | 10 +- classes/class_visibleonscreennotifier3d.rst | 18 +-- 51 files changed, 368 insertions(+), 196 deletions(-) diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 11ca3076501..2c1b9e30e0f 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -5416,7 +5416,7 @@ Decodes a byte array back to a :ref:`Variant` value. Decoding obj :ref:`Variant` **ceil** **(** :ref:`Variant` x **)** -Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`. +Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. :: @@ -5718,7 +5718,7 @@ For exponents to other bases use the method :ref:`pow` **floor** **(** :ref:`Variant` x **)** -Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`. +Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. :: @@ -6825,7 +6825,7 @@ If ``delta`` is negative, this function will rotate away from ``to``, toward the :ref:`Variant` **round** **(** :ref:`Variant` x **)** -Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`. +Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. :: diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 2b0a60ea6b6..113d74bdf4e 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -585,7 +585,11 @@ Returns ``true`` if the AABBs are not equal. :ref:`AABB` **operator *** **(** :ref:`Transform3D` right **)** -Inversely transforms (multiplies) the **AABB** by the given :ref:`Transform3D` transformation matrix. +Inversely transforms (multiplies) the **AABB** by the given :ref:`Transform3D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``aabb * transform`` is equivalent to ``transform.inverse() * aabb``. See :ref:`Transform3D.inverse`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * aabb`` can be used instead. See :ref:`Transform3D.affine_inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_animation.rst b/classes/class_animation.rst index 750d1d97101..2f8b3fc1ad5 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -877,7 +877,7 @@ Compress the animation and all its tracks in-place. This will make :ref:`track_i void **copy_track** **(** :ref:`int` track_idx, :ref:`Animation` to_animation **)** -Adds a new track that is a copy of the given track from ``to_animation``. +Adds a new track to ``to_animation`` that is a copy of the given track from this animation. .. rst-class:: classref-item-separator diff --git a/classes/class_audiostreamgeneratorplayback.rst b/classes/class_audiostreamgeneratorplayback.rst index bb13ffabb02..466daa3bb80 100644 --- a/classes/class_audiostreamgeneratorplayback.rst +++ b/classes/class_audiostreamgeneratorplayback.rst @@ -103,9 +103,7 @@ Returns the number of frames that can be pushed to the audio sample data buffer :ref:`int` **get_skips** **(** **)** |const| -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +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. .. rst-class:: classref-item-separator diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index afca8535072..4b5dfbecfa8 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -1227,7 +1227,7 @@ The object's X axis will always face the camera. :ref:`BillboardMode` **BILLBOARD_PARTICLES** = ``3`` -Used for particle systems when assigned to :ref:`GPUParticles3D` and :ref:`CPUParticles3D` nodes. Enables ``particles_anim_*`` properties. +Used for particle systems when assigned to :ref:`GPUParticles3D` and :ref:`CPUParticles3D` nodes (flipbook animation). Enables ``particles_anim_*`` properties. The :ref:`ParticleProcessMaterial.anim_speed_min` or :ref:`CPUParticles3D.anim_speed_min` should also be set to a value bigger than zero for the animation to play. diff --git a/classes/class_button.rst b/classes/class_button.rst index 6016f5afe1b..5fed12417f8 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -598,9 +598,7 @@ Font size of the **Button**'s text. :ref:`Texture2D` **icon** -.. container:: contribute - - There is currently no description for this theme property. Please help us by :ref:`contributing one `! +Default icon for the **Button**. Appears only if :ref:`icon` is not assigned. .. rst-class:: classref-item-separator diff --git a/classes/class_concavepolygonshape2d.rst b/classes/class_concavepolygonshape2d.rst index e79165e2760..83b4a241d7c 100644 --- a/classes/class_concavepolygonshape2d.rst +++ b/classes/class_concavepolygonshape2d.rst @@ -21,7 +21,7 @@ Description A 2D polyline shape, intended for use in physics. Used internally in :ref:`CollisionPolygon2D` when it's in :ref:`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, :ref:`ConvexPolygonShape2D` is *hollow* 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 *hollow* even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. \ **Note:** When used for collision, **ConcavePolygonShape2D** is intended to work with static :ref:`CollisionShape2D` nodes like :ref:`StaticBody2D` and will likely not behave well for :ref:`CharacterBody2D`\ s or :ref:`RigidBody2D`\ s in a mode other than Static. diff --git a/classes/class_concavepolygonshape3d.rst b/classes/class_concavepolygonshape3d.rst index 042970feefb..268074f54fa 100644 --- a/classes/class_concavepolygonshape3d.rst +++ b/classes/class_concavepolygonshape3d.rst @@ -21,7 +21,7 @@ Description A 3D trimesh shape, intended for use in physics. Usually used to provide a shape for a :ref:`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, :ref:`ConvexPolygonShape3D` is *hollow* 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 *hollow* even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. \ **Note:** When used for collision, **ConcavePolygonShape3D** is intended to work with static :ref:`CollisionShape3D` nodes like :ref:`StaticBody3D` and will likely not behave well for :ref:`CharacterBody3D`\ s or :ref:`RigidBody3D`\ s in a mode other than Static. diff --git a/classes/class_control.rst b/classes/class_control.rst index f8d37faa57b..c3146cbc6de 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -1131,7 +1131,9 @@ Sent when the node needs to refresh its theme items. This happens in one of the **NOTIFICATION_SCROLL_BEGIN** = ``47`` -Sent when this node is inside a :ref:`ScrollContainer` which has begun being scrolled. +Sent when this node is inside a :ref:`ScrollContainer` which has begun being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + +\ **Note:** This signal is only emitted on Android or iOS, or on desktop/web platforms when :ref:`ProjectSettings.input_devices/pointing/emulate_touch_from_mouse` is enabled. .. _class_Control_constant_NOTIFICATION_SCROLL_END: @@ -1139,7 +1141,9 @@ Sent when this node is inside a :ref:`ScrollContainer` wh **NOTIFICATION_SCROLL_END** = ``48`` -Sent when this node is inside a :ref:`ScrollContainer` which has stopped being scrolled. +Sent when this node is inside a :ref:`ScrollContainer` which has stopped being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + +\ **Note:** This signal is only emitted on Android or iOS, or on desktop/web platforms when :ref:`ProjectSettings.input_devices/pointing/emulate_touch_from_mouse` is enabled. .. _class_Control_constant_NOTIFICATION_LAYOUT_DIRECTION_CHANGED: diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 44bf53e12d1..0664ca4713f 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -532,6 +532,48 @@ void **merge** **(** :ref:`Dictionary` dictionary, :ref:`bool< Adds entries from ``dictionary`` to this dictionary. By default, duplicate keys are not copied over, unless ``overwrite`` is ``true``. + +.. tabs:: + + .. code-tab:: 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" } + + .. code-tab:: 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" } + + + +\ **Note:** :ref:`merge` is *not* recursive. Nested dictionaries are considered as keys that can be overwritten or not depending on the value of ``overwrite``, but they will never be merged together. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_gpuparticles2d.rst b/classes/class_gpuparticles2d.rst index b80b11ae97b..ce2af27c363 100644 --- a/classes/class_gpuparticles2d.rst +++ b/classes/class_gpuparticles2d.rst @@ -240,7 +240,9 @@ Property Descriptions - void **set_amount** **(** :ref:`int` value **)** - :ref:`int` **get_amount** **(** **)** -Number of particles emitted in one emission cycle. +The number of particles to emit in one emission cycle. The effective emission rate is ``(amount * amount_ratio) / lifetime`` particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if :ref:`amount_ratio` is decreased. + +\ **Note:** Changing this value will cause the particle system to restart. To avoid this, change :ref:`amount_ratio` instead. .. rst-class:: classref-item-separator @@ -259,7 +261,7 @@ Number of particles emitted in one emission cycle. The ratio of particles that should actually be emitted. If set to a value lower than ``1.0``, this will set the amount of emitted particles throughout the lifetime to ``amount * amount_ratio``. Unlike changing :ref:`amount`, changing :ref:`amount_ratio` while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. :ref:`amount_ratio` can be used to create effects that make the number of emitted particles vary over time. -\ **Note:** Reducing the :ref:`amount_ratio` has no performance benefit, since resources need to be allocated and processed for the total :ref:`amount` of particles regardless of the :ref:`amount_ratio`. +\ **Note:** Reducing the :ref:`amount_ratio` has no performance benefit, since resources need to be allocated and processed for the total :ref:`amount` of particles regardless of the :ref:`amount_ratio`. If you don't intend to change the number of particles emitted while the particles are emitting, make sure :ref:`amount_ratio` is set to ``1`` and change :ref:`amount` to your liking instead. .. rst-class:: classref-item-separator @@ -276,7 +278,9 @@ The ratio of particles that should actually be emitted. If set to a value lower - void **set_collision_base_size** **(** :ref:`float` value **)** - :ref:`float` **get_collision_base_size** **(** **)** -Multiplier for particle's collision radius. ``1.0`` corresponds to the size of the sprite. +Multiplier for particle's collision radius. ``1.0`` 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 :ref:`ParticleProcessMaterial.collision_mode` is :ref:`ParticleProcessMaterial.COLLISION_RIGID` or :ref:`ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT`. + +\ **Note:** Particles always have a spherical collision shape. .. rst-class:: classref-item-separator @@ -380,7 +384,7 @@ If ``true``, results in fractional delta calculation which has a smoother partic Causes all the particles in this node to interpolate towards the end of their lifetime. -\ **Note**: This only works when used with a :ref:`ParticleProcessMaterial`. It needs to be manually implemented for custom process shaders. +\ **Note:** This only works when used with a :ref:`ParticleProcessMaterial`. It needs to be manually implemented for custom process shaders. .. rst-class:: classref-item-separator @@ -414,7 +418,7 @@ Enables particle interpolation, which makes the particle movement smoother when - void **set_lifetime** **(** :ref:`float` value **)** - :ref:`float` **get_lifetime** **(** **)** -Amount of time each particle will exist. +The amount of time each particle will exist (in seconds). The effective emission rate is ``(amount * amount_ratio) / lifetime`` particles per second. .. rst-class:: classref-item-separator @@ -533,7 +537,9 @@ Particle system's running speed scaling ratio. A value of ``0`` can be used to p - void **set_sub_emitter** **(** :ref:`NodePath` value **)** - :ref:`NodePath` **get_sub_emitter** **(** **)** -The :ref:`NodePath` to the **GPUParticles2D** used for sub-emissions. +Path to another **GPUParticles2D** node that will be used as a subemitter (see :ref:`ParticleProcessMaterial.sub_emitter_mode`). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more. + +\ **Note:** When :ref:`sub_emitter` is set, the target **GPUParticles2D** node will no longer emit particles on its own. .. rst-class:: classref-item-separator @@ -550,7 +556,9 @@ The :ref:`NodePath` to the **GPUParticles2D** used for sub-emiss - void **set_texture** **(** :ref:`Texture2D` value **)** - :ref:`Texture2D` **get_texture** **(** **)** -Particle texture. If ``null``, particles will be squares. +Particle texture. If ``null``, particles will be squares with a size of 1×1 pixels. + +\ **Note:** To use a flipbook texture, assign a new :ref:`CanvasItemMaterial` to the **GPUParticles2D**'s :ref:`CanvasItem.material` property, then enable :ref:`CanvasItemMaterial.particles_animation` and set :ref:`CanvasItemMaterial.particles_anim_h_frames`, :ref:`CanvasItemMaterial.particles_anim_v_frames`, and :ref:`CanvasItemMaterial.particles_anim_loop` to match the flipbook texture. .. rst-class:: classref-item-separator diff --git a/classes/class_gpuparticles3d.rst b/classes/class_gpuparticles3d.rst index e270cbd66ca..2079c7ed48b 100644 --- a/classes/class_gpuparticles3d.rst +++ b/classes/class_gpuparticles3d.rst @@ -317,7 +317,9 @@ Property Descriptions - void **set_amount** **(** :ref:`int` value **)** - :ref:`int` **get_amount** **(** **)** -Number of particles to emit. +The number of particles to emit in one emission cycle. The effective emission rate is ``(amount * amount_ratio) / lifetime`` particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if :ref:`amount_ratio` is decreased. + +\ **Note:** Changing this value will cause the particle system to restart. To avoid this, change :ref:`amount_ratio` instead. .. rst-class:: classref-item-separator @@ -336,7 +338,7 @@ Number of particles to emit. The ratio of particles that should actually be emitted. If set to a value lower than ``1.0``, this will set the amount of emitted particles throughout the lifetime to ``amount * amount_ratio``. Unlike changing :ref:`amount`, changing :ref:`amount_ratio` while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. :ref:`amount_ratio` can be used to create effects that make the number of emitted particles vary over time. -\ **Note:** Reducing the :ref:`amount_ratio` has no performance benefit, since resources need to be allocated and processed for the total :ref:`amount` of particles regardless of the :ref:`amount_ratio`. +\ **Note:** Reducing the :ref:`amount_ratio` has no performance benefit, since resources need to be allocated and processed for the total :ref:`amount` of particles regardless of the :ref:`amount_ratio`. If you don't intend to change the number of particles emitted while the particles are emitting, make sure :ref:`amount_ratio` is set to ``1`` and change :ref:`amount` to your liking instead. .. rst-class:: classref-item-separator @@ -353,9 +355,9 @@ The ratio of particles that should actually be emitted. If set to a value lower - void **set_collision_base_size** **(** :ref:`float` value **)** - :ref:`float` **get_collision_base_size** **(** **)** -.. container:: contribute +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 :ref:`ParticleProcessMaterial.collision_mode` is :ref:`ParticleProcessMaterial.COLLISION_RIGID` or :ref:`ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT`. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** Particles always have a spherical collision shape. .. rst-class:: classref-item-separator @@ -565,7 +567,7 @@ If ``true``, results in fractional delta calculation which has a smoother partic Causes all the particles in this node to interpolate towards the end of their lifetime. -\ **Note**: This only works when used with a :ref:`ParticleProcessMaterial`. It needs to be manually implemented for custom process shaders. +\ **Note:** This only works when used with a :ref:`ParticleProcessMaterial`. It needs to be manually implemented for custom process shaders. .. rst-class:: classref-item-separator @@ -599,7 +601,7 @@ Enables particle interpolation, which makes the particle movement smoother when - void **set_lifetime** **(** :ref:`float` value **)** - :ref:`float` **get_lifetime** **(** **)** -Amount of time each particle will exist. +The amount of time each particle will exist (in seconds). The effective emission rate is ``(amount * amount_ratio) / lifetime`` particles per second. .. rst-class:: classref-item-separator @@ -718,9 +720,9 @@ Speed scaling ratio. A value of ``0`` can be used to pause the particles. - void **set_sub_emitter** **(** :ref:`NodePath` value **)** - :ref:`NodePath` **get_sub_emitter** **(** **)** -.. container:: contribute +Path to another **GPUParticles3D** node that will be used as a subemitter (see :ref:`ParticleProcessMaterial.sub_emitter_mode`). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** When :ref:`sub_emitter` is set, the target **GPUParticles3D** node will no longer emit particles on its own. .. rst-class:: classref-item-separator @@ -794,10 +796,12 @@ The amount of time the particle's trail should represent (in seconds). Only effe - void **set_visibility_aabb** **(** :ref:`AABB` value **)** - :ref:`AABB` **get_visibility_aabb** **(** **)** -The :ref:`AABB` that determines the node's region which needs to be visible on screen for the particle system to be active. +The :ref:`AABB` that determines the node's region which needs to be visible on screen for the particle system to be active. :ref:`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 :ref:`AABB` can be grown via code or with the **Particles → Generate AABB** editor tool. +\ **Note:** :ref:`visibility_aabb` is overridden by :ref:`GeometryInstance3D.custom_aabb` if that property is set to a non-default value. + .. rst-class:: classref-section-separator ---- diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 1a5b4b78488..325cd0d3184 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -1100,7 +1100,7 @@ Disallows to disconnect nodes when dragging from the right port of the :ref:`Gra void **set_connection_activity** **(** :ref:`StringName` from_node, :ref:`int` from_port, :ref:`StringName` to_node, :ref:`int` to_port, :ref:`float` amount **)** -Sets the coloration of the connection between ``from_node``'s ``from_port`` and ``to_node``'s ``to_port`` with the color provided in the :ref:`activity` theme property. +Sets the coloration of the connection between ``from_node``'s ``from_port`` and ``to_node``'s ``to_port`` with the color provided in the :ref:`activity` theme property. The color is linearly interpolated between the connection color and the activity color using ``amount`` as weight. .. rst-class:: classref-item-separator @@ -1129,9 +1129,7 @@ Theme Property Descriptions :ref:`Color` **activity** = ``Color(1, 1, 1, 1)`` -.. container:: contribute - - There is currently no description for this theme property. Please help us by :ref:`contributing one `! +Color of the connection's activity (see :ref:`set_connection_activity`). .. rst-class:: classref-item-separator diff --git a/classes/class_immediatemesh.rst b/classes/class_immediatemesh.rst index 2ab241c87dc..545b2f79765 100644 --- a/classes/class_immediatemesh.rst +++ b/classes/class_immediatemesh.rst @@ -35,6 +35,15 @@ Here's a sample on how to generate a triangular face: mesh.surface_add_vertex(Vector3.ZERO) mesh.surface_end() + .. code-tab:: csharp + + var mesh = new ImmediateMesh(); + mesh.SurfaceBegin(Mesh.PrimitiveType.Triangles); + mesh.SurfaceAddVertex(Vector3.Left); + mesh.SurfaceAddVertex(Vector3.Forward); + mesh.SurfaceAddVertex(Vector3.Zero); + mesh.SurfaceEnd(); + \ **Note:** Generating complex geometries with **ImmediateMesh** is highly inefficient. Instead, it is designed to generate simple geometry that changes often. diff --git a/classes/class_importermesh.rst b/classes/class_importermesh.rst index 637190c926a..712bbeede5a 100644 --- a/classes/class_importermesh.rst +++ b/classes/class_importermesh.rst @@ -255,7 +255,7 @@ If not yet cached and ``base_mesh`` is provided, ``base_mesh`` will be used and :ref:`Array` **get_surface_arrays** **(** :ref:`int` surface_idx **)** |const| -Returns the arrays for the vertices, normals, uvs, etc. that make up the requested surface. See :ref:`add_surface`. +Returns the arrays for the vertices, normals, UVs, etc. that make up the requested surface. See :ref:`add_surface`. .. rst-class:: classref-item-separator diff --git a/classes/class_light3d.rst b/classes/class_light3d.rst index 0851cbfb347..a1d86de7c59 100644 --- a/classes/class_light3d.rst +++ b/classes/class_light3d.rst @@ -331,6 +331,8 @@ Light is ignored when baking. This is the fastest mode, but the light will be ta Light is taken into account in static baking (:ref:`VoxelGI`, :ref:`LightmapGI`, SDFGI (:ref:`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. +\ **Note:** The light is not baked in :ref:`LightmapGI` if :ref:`editor_only` is ``true``. + .. _class_Light3D_constant_BAKE_DYNAMIC: .. rst-class:: classref-enumeration-constant @@ -435,7 +437,7 @@ The distance from the camera at which the light's shadow cuts off (in 3D units). - void **set_editor_only** **(** :ref:`bool` value **)** - :ref:`bool` **is_editor_only** **(** **)** -If ``true``, the light only appears in the editor and will not be visible at runtime. +If ``true``, the light only appears in the editor and will not be visible at runtime. If ``true``, the light will never be baked in :ref:`LightmapGI` regardless of its :ref:`light_bake_mode`. .. rst-class:: classref-item-separator diff --git a/classes/class_lightmapgi.rst b/classes/class_lightmapgi.rst index b5dda39a98a..9b9bf0166ad 100644 --- a/classes/class_lightmapgi.rst +++ b/classes/class_lightmapgi.rst @@ -420,7 +420,7 @@ The strength of denoising step applied to the generated lightmaps. Only effectiv - void **set_directional** **(** :ref:`bool` value **)** - :ref:`bool` **is_directional** **(** **)** -If ``true``, 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 (:ref:`Light3D.light_bake_mode` set to :ref:`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 ``true``, 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 (:ref:`Light3D.light_bake_mode` set to :ref:`Light3D.BAKE_STATIC` and with :ref:`Light3D.editor_only` set to ``false``). 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. \ **Note:** The property's name has no relationship with :ref:`DirectionalLight3D`. :ref:`directional` works with all light types. diff --git a/classes/class_lightmapgidata.rst b/classes/class_lightmapgidata.rst index dd0cfcfead5..c8bbcd6fce6 100644 --- a/classes/class_lightmapgidata.rst +++ b/classes/class_lightmapgidata.rst @@ -29,9 +29,11 @@ Properties .. table:: :widths: auto - +---------------------------------------------+-------------------------------------------------------------------+ - | :ref:`TextureLayered` | :ref:`light_texture` | - +---------------------------------------------+-------------------------------------------------------------------+ + +-----------------------------------------------+---------------------------------------------------------------------------+--------+ + | :ref:`TextureLayered` | :ref:`light_texture` | | + +-----------------------------------------------+---------------------------------------------------------------------------+--------+ + | :ref:`TextureLayered[]` | :ref:`lightmap_textures` | ``[]`` | + +-----------------------------------------------+---------------------------------------------------------------------------+--------+ .. rst-class:: classref-reftable-group @@ -77,6 +79,25 @@ Property Descriptions The lightmap atlas texture generated by the lightmapper. +\ *Deprecated.* The lightmap atlas can now have multiple textures. See :ref:`lightmap_textures`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_LightmapGIData_property_lightmap_textures: + +.. rst-class:: classref-property + +:ref:`TextureLayered[]` **lightmap_textures** = ``[]`` + +.. rst-class:: classref-property-setget + +- void **set_lightmap_textures** **(** :ref:`TextureLayered[]` value **)** +- :ref:`TextureLayered[]` **get_lightmap_textures** **(** **)** + +The lightmap atlas textures generated by the lightmapper. + .. rst-class:: classref-section-separator ---- diff --git a/classes/class_lightoccluder2d.rst b/classes/class_lightoccluder2d.rst index 7f080f63bab..f325c8b2dad 100644 --- a/classes/class_lightoccluder2d.rst +++ b/classes/class_lightoccluder2d.rst @@ -98,9 +98,7 @@ The LightOccluder2D's occluder light mask. The LightOccluder2D will cast shadows - void **set_as_sdf_collision** **(** :ref:`bool` value **)** - :ref:`bool` **is_set_as_sdf_collision** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +If enabled, the occluder will be part of a real-time generated signed distance field that can be used in custom shaders. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_lineedit.rst b/classes/class_lineedit.rst index a3e997b1c4c..1988cc5418e 100644 --- a/classes/class_lineedit.rst +++ b/classes/class_lineedit.rst @@ -998,7 +998,7 @@ If ``true``, every character is replaced with the secret character (see :ref:`se - void **set_secret_character** **(** :ref:`String` value **)** - :ref:`String` **get_secret_character** **(** **)** -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. .. rst-class:: classref-item-separator diff --git a/classes/class_mesh.rst b/classes/class_mesh.rst index fc6ff45b1e8..abdcf86c4b5 100644 --- a/classes/class_mesh.rst +++ b/classes/class_mesh.rst @@ -589,6 +589,14 @@ Flag used to mark that the mesh contains up to 8 bone influences per vertex. Thi Flag used to mark that the mesh intentionally contains no vertex array. +.. _class_Mesh_constant_ARRAY_FLAG_COMPRESS_ATTRIBUTES: + +.. rst-class:: classref-enumeration-constant + +:ref:`ArrayFormat` **ARRAY_FLAG_COMPRESS_ATTRIBUTES** = ``536870912`` + +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. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_multiplayerapiextension.rst b/classes/class_multiplayerapiextension.rst index b06a29e93e6..44d7c945d01 100644 --- a/classes/class_multiplayerapiextension.rst +++ b/classes/class_multiplayerapiextension.rst @@ -35,7 +35,7 @@ The following example augment the default implementation (:ref:`SceneMultiplayer 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 @@ -45,13 +45,16 @@ The following example augment the default implementation (:ref:`SceneMultiplayer 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: @@ -59,7 +62,7 @@ The following example augment the default implementation (:ref:`SceneMultiplayer 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/classes/class_navigationagent3d.rst b/classes/class_navigationagent3d.rst index 0825bd14e86..abcba3bae7d 100644 --- a/classes/class_navigationagent3d.rst +++ b/classes/class_navigationagent3d.rst @@ -59,6 +59,8 @@ Properties +------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`float` | :ref:`height` | ``1.0`` | +------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`keep_y_velocity` | ``true`` | + +------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`int` | :ref:`max_neighbors` | ``10`` | +------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`float` | :ref:`max_speed` | ``10.0`` | @@ -411,6 +413,23 @@ The height of the avoidance agent. Agents will ignore other agents or obstacles ---- +.. _class_NavigationAgent3D_property_keep_y_velocity: + +.. rst-class:: classref-property + +:ref:`bool` **keep_y_velocity** = ``true`` + +.. rst-class:: classref-property-setget + +- void **set_keep_y_velocity** **(** :ref:`bool` value **)** +- :ref:`bool` **get_keep_y_velocity** **(** **)** + +If ``true``, 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. + +.. rst-class:: classref-item-separator + +---- + .. _class_NavigationAgent3D_property_max_neighbors: .. rst-class:: classref-property diff --git a/classes/class_node.rst b/classes/class_node.rst index 9f5141d5698..fa27fc6b558 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -769,7 +769,7 @@ Notification received every frame when the internal physics process flag is set **NOTIFICATION_POST_ENTER_TREE** = ``27`` -Notification received when the node is ready, just before :ref:`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 :ref:`NOTIFICATION_READY` is received. Unlike the latter, it's sent every time the node enters the tree, instead of only once. .. _class_Node_constant_NOTIFICATION_DISABLED: diff --git a/classes/class_object.rst b/classes/class_object.rst index a1c25cbbfd8..7688daa326d 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -21,7 +21,7 @@ Description An advanced :ref:`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 :ref:`Sprite2D` instance is able to call :ref:`Node.add_child` because it inherits from :ref:`Node`. -You can create new instances, using ``Object.new()`` in GDScript, or ``new Object`` in C#. +You can create new instances, using ``Object.new()`` in GDScript, or ``new GodotObject`` in C#. To delete an Object instance, call :ref:`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, :ref:`RefCounted` (and by extension :ref:`Resource`) deletes itself when no longer referenced, and :ref:`Node` deletes its children when freed. @@ -449,7 +449,7 @@ The example below displays ``hammer_type`` in the Inspector dock, only if ``hold void **_init** **(** **)** |virtual| -Called when the object's script is instantiated, oftentimes after the object is initialized in memory (through ``Object.new()`` in GDScript, or ``new Object`` 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 ``Object.new()`` in GDScript, or ``new GodotObject`` in C#). It can be also defined to take in parameters. This method is similar to a constructor in most programming languages. \ **Note:** If :ref:`_init` is defined with *required* parameters, the Object with script may only be created directly. If any other means (such as :ref:`PackedScene.instantiate` or :ref:`Node.duplicate`) are used, the script's initialization will fail. @@ -542,6 +542,7 @@ Combined with :ref:`_get` and :ref:`_get_property_list # Storing the value in the fake property. internal_data["fake_property"] = value return true + return false func _get_property_list(): return [ @@ -552,7 +553,7 @@ Combined with :ref:`_get` and :ref:`_get_property_list 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/classes/class_packedvector2array.rst b/classes/class_packedvector2array.rst index 35874ee6c2f..d41288c9db4 100644 --- a/classes/class_packedvector2array.rst +++ b/classes/class_packedvector2array.rst @@ -463,7 +463,11 @@ Returns ``true`` if contents of the arrays differ. :ref:`PackedVector2Array` **operator *** **(** :ref:`Transform2D` right **)** -Transforms (multiplies) all vectors in the array by the :ref:`Transform2D` matrix. +Returns a new **PackedVector2Array** with all vectors in this array inversely transformed (multiplied) by the given :ref:`Transform2D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``array * transform`` is equivalent to ``transform.inverse() * array``. See :ref:`Transform2D.inverse`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * array`` can be used instead. See :ref:`Transform2D.affine_inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_packedvector3array.rst b/classes/class_packedvector3array.rst index e6072f8f31a..98bc0ead1d4 100644 --- a/classes/class_packedvector3array.rst +++ b/classes/class_packedvector3array.rst @@ -456,7 +456,11 @@ Returns ``true`` if contents of the arrays differ. :ref:`PackedVector3Array` **operator *** **(** :ref:`Transform3D` right **)** -Transforms (multiplies) all vectors in the array by the :ref:`Transform3D` matrix. +Returns a new **PackedVector3Array** with all vectors in this array inversely transformed (multiplied) by the given :ref:`Transform3D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``array * transform`` is equivalent to ``transform.inverse() * array``. See :ref:`Transform3D.inverse`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * array`` can be used instead. See :ref:`Transform3D.affine_inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_particleprocessmaterial.rst b/classes/class_particleprocessmaterial.rst index 6dbb10c4ad1..388999bff1c 100644 --- a/classes/class_particleprocessmaterial.rst +++ b/classes/class_particleprocessmaterial.rst @@ -875,7 +875,7 @@ Minimum equivalent of :ref:`anim_speed_max` value **)** - :ref:`bool` **is_attractor_interaction_enabled** **(** **)** -True if the interaction with particle attractors is enabled. +If ``true``, interaction with particle attractors is enabled. In 3D, attraction only occurs within the area defined by the :ref:`GPUParticles3D` node's :ref:`GPUParticles3D.visibility_aabb`. .. rst-class:: classref-item-separator @@ -928,7 +928,7 @@ The particles' friction. Values range from ``0`` (frictionless) to ``1`` (maximu The particles' collision mode. -\ **Note:** 3D Particles can only collide with :ref:`GPUParticlesCollision3D` nodes, not :ref:`PhysicsBody3D` nodes. To make particles collide with various objects, you can add :ref:`GPUParticlesCollision3D` nodes as children of :ref:`PhysicsBody3D` nodes. +\ **Note:** 3D Particles can only collide with :ref:`GPUParticlesCollision3D` nodes, not :ref:`PhysicsBody3D` nodes. To make particles collide with various objects, you can add :ref:`GPUParticlesCollision3D` nodes as children of :ref:`PhysicsBody3D` nodes. In 3D, collisions only occur within the area defined by the :ref:`GPUParticles3D` node's :ref:`GPUParticles3D.visibility_aabb`. \ **Note:** 2D Particles can only collide with :ref:`LightOccluder2D` nodes, not :ref:`PhysicsBody2D` nodes. @@ -947,7 +947,7 @@ The particles' collision mode. - void **set_collision_use_scale** **(** :ref:`bool` value **)** - :ref:`bool` **is_collision_using_scale** **(** **)** -Should collision take scale into account. +If ``true``, :ref:`GPUParticles3D.collision_base_size` is multiplied by the particle's effective scale (see :ref:`scale_min`, :ref:`scale_max`, :ref:`scale_curve`, and :ref:`scale_over_velocity_curve`). .. rst-class:: classref-item-separator @@ -1950,9 +1950,9 @@ Each particle's initial direction range from ``+spread`` to ``-spread`` degrees. - void **set_sub_emitter_amount_at_collision** **(** :ref:`int` value **)** - :ref:`int` **get_sub_emitter_amount_at_collision** **(** **)** -Sub particle amount on collision. +The amount of particles to spawn from the subemitter node when a collision occurs. When combined with :ref:`COLLISION_HIDE_ON_CONTACT` on the main particles material, this can be used to achieve effects such as raindrops hitting the ground. -Maximum amount set in the sub particles emitter. +\ **Note:** This value shouldn't exceed :ref:`GPUParticles2D.amount` or :ref:`GPUParticles3D.amount` defined on the *subemitter node* (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. .. rst-class:: classref-item-separator @@ -1969,9 +1969,9 @@ Maximum amount set in the sub particles emitter. - void **set_sub_emitter_amount_at_end** **(** :ref:`int` value **)** - :ref:`int` **get_sub_emitter_amount_at_end** **(** **)** -.. container:: contribute +The amount of particles to spawn from the subemitter node when the particle expires. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** This value shouldn't exceed :ref:`GPUParticles2D.amount` or :ref:`GPUParticles3D.amount` defined on the *subemitter node* (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. .. rst-class:: classref-item-separator @@ -1988,9 +1988,9 @@ Maximum amount set in the sub particles emitter. - void **set_sub_emitter_frequency** **(** :ref:`float` value **)** - :ref:`float` **get_sub_emitter_frequency** **(** **)** -.. container:: contribute +The frequency at which particles should be emitted from the subemitter node. One particle will be spawned every :ref:`sub_emitter_frequency` seconds. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** This value shouldn't exceed :ref:`GPUParticles2D.amount` or :ref:`GPUParticles3D.amount` defined on the *subemitter node* (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. .. rst-class:: classref-item-separator @@ -2007,9 +2007,7 @@ Maximum amount set in the sub particles emitter. - void **set_sub_emitter_keep_velocity** **(** :ref:`bool` value **)** - :ref:`bool` **get_sub_emitter_keep_velocity** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +If ``true``, the subemitter inherits the parent particle's velocity when it spawns. .. rst-class:: classref-item-separator @@ -2026,9 +2024,7 @@ Maximum amount set in the sub particles emitter. - void **set_sub_emitter_mode** **(** :ref:`SubEmitterMode` value **)** - :ref:`SubEmitterMode` **get_sub_emitter_mode** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +The particle subemitter mode (see :ref:`GPUParticles2D.sub_emitter` and :ref:`GPUParticles3D.sub_emitter`). .. rst-class:: classref-item-separator @@ -2299,9 +2295,7 @@ A :ref:`CurveTexture` that defines the maximum velocity of a - void **set_velocity_pivot** **(** :ref:`Vector3` value **)** - :ref:`Vector3` **get_velocity_pivot** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +A pivot point used to calculate radial and orbital velocity of particles. .. rst-class:: classref-section-separator diff --git a/classes/class_plane.rst b/classes/class_plane.rst index 170d3ec128a..30c2675f7ed 100644 --- a/classes/class_plane.rst +++ b/classes/class_plane.rst @@ -475,6 +475,8 @@ Returns ``true`` if the planes are not equal. Inversely transforms (multiplies) the **Plane** by the given :ref:`Transform3D` transformation matrix. +\ ``plane * transform`` is equivalent to ``transform.affine_inverse() * plane``. See :ref:`Transform3D.affine_inverse`. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_popupmenu.rst b/classes/class_popupmenu.rst index e0aaf7c36c3..ae8b6dfcd23 100644 --- a/classes/class_popupmenu.rst +++ b/classes/class_popupmenu.rst @@ -668,7 +668,7 @@ If ``allow_echo`` is ``true``, the shortcut can be activated with echo events. void **add_submenu_item** **(** :ref:`String` label, :ref:`String` submenu, :ref:`int` id=-1 **)** -Adds an item that will act as a submenu of the parent **PopupMenu** node when clicked. The ``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 ``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 ``ui_select`` or ``ui_right`` input actions. An ``id`` can optionally be provided. If no ``id`` is provided, one will be created from the index. diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 47b3ed2d3bd..f3fa39d0247 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -129,6 +129,10 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`audio/general/3d_panning_strength` | ``0.5`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`audio/general/ios/mix_with_others` | ``false`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`audio/general/ios/session_category` | ``0`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`audio/general/text_to_speech` | ``false`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`audio/video/video_delay_compensation_ms` | ``0`` | @@ -1305,22 +1309,24 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/environment/volumetric_fog/volume_size` | ``64`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver.android` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver.android` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver.ios` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver.ios` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver.linuxbsd` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver.linuxbsd` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver.macos` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver.macos` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver.web` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver.web` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/gl_compatibility/driver.windows` | ``"opengl3"`` | + | :ref:`String` | :ref:`rendering/gl_compatibility/driver.windows` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`rendering/gl_compatibility/fallback_to_angle` | ``true`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`rendering/gl_compatibility/fallback_to_native` | ``true`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`rendering/gl_compatibility/force_angle_on_devices` | ``[]`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/gl_compatibility/item_buffer_size` | ``16384`` | @@ -1445,17 +1451,17 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/renderer/rendering_method.web` | ``"gl_compatibility"`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/rendering_device/driver` | ``"vulkan"`` | + | :ref:`String` | :ref:`rendering/rendering_device/driver` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/rendering_device/driver.android` | ``"vulkan"`` | + | :ref:`String` | :ref:`rendering/rendering_device/driver.android` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/rendering_device/driver.ios` | ``"vulkan"`` | + | :ref:`String` | :ref:`rendering/rendering_device/driver.ios` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/rendering_device/driver.linuxbsd` | ``"vulkan"`` | + | :ref:`String` | :ref:`rendering/rendering_device/driver.linuxbsd` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/rendering_device/driver.macos` | ``"vulkan"`` | + | :ref:`String` | :ref:`rendering/rendering_device/driver.macos` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`rendering/rendering_device/driver.windows` | ``"vulkan"`` | + | :ref:`String` | :ref:`rendering/rendering_device/driver.windows` | | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`rendering/rendering_device/pipeline_cache/save_chunk_size_mb` | ``3.0`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ @@ -2184,6 +2190,32 @@ The default value of ``0.5`` is tuned for headphones. When using speakers, you m ---- +.. _class_ProjectSettings_property_audio/general/ios/mix_with_others: + +.. rst-class:: classref-property + +:ref:`bool` **audio/general/ios/mix_with_others** = ``false`` + +Sets the `mixWithOthers `__ option for the AVAudioSession on iOS. This will override the mix behavior, if the category is set to ``Play and Record``, ``Playback``, or ``Multi Route``. + +\ ``Ambient`` always has this set per default. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ProjectSettings_property_audio/general/ios/session_category: + +.. rst-class:: classref-property + +:ref:`int` **audio/general/ios/session_category** = ``0`` + +Sets the `AVAudioSessionCategory `__ on iOS. Use the ``Playback`` category to get sound output, even if the phone is in silent mode. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_property_audio/general/text_to_speech: .. rst-class:: classref-property @@ -2856,6 +2888,8 @@ When set to ``warn`` or ``error``, produces a warning or an error respectively w When set to ``warn`` or ``error``, 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. +\ **Note:** This warning is recommended together with :ref:`EditorSettings.text_editor/completion/add_type_hints` to help achieve type safety. + .. rst-class:: classref-item-separator ---- @@ -3866,7 +3900,7 @@ On desktop platforms, overrides the game's initial window height. See also :ref: On desktop platforms, overrides the game's initial window width. See also :ref:`display/window/size/window_height_override`, :ref:`display/window/size/viewport_width` and :ref:`display/window/size/viewport_height`. -\ **Note:** By default, or when set to ``0``, the initial window width is the viewport :ref:`display/window/size/viewport_width`. This setting is ignored on iOS, Android, and Web. +\ **Note:** By default, or when set to ``0``, the initial window width is the :ref:`display/window/size/viewport_width`. This setting is ignored on iOS, Android, and Web. .. rst-class:: classref-item-separator @@ -3924,6 +3958,12 @@ The scale factor multiplier to use for 2D elements. This multiplies the final sc The policy to use to determine the final scale factor for 2D elements. This affects how :ref:`display/window/stretch/scale` is applied, in addition to the automatic scale factor determined by :ref:`display/window/stretch/mode`. +\ **"fractional"**: The scale factor will not be modified. + +\ **"integer"**: 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. + +\ **Note:** 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 :ref:`Window.min_size` to the same value as the base viewport size defined in :ref:`display/window/size/viewport_width` and :ref:`display/window/size/viewport_height`. + .. rst-class:: classref-item-separator ---- @@ -9066,7 +9106,7 @@ Controls how much physics ticks are synchronized with real time. For 0 or less, \ **Note:** For best results, when using a custom physics interpolation solution, the physics jitter fix should be disabled by setting :ref:`physics/common/physics_jitter_fix` to ``0``. -\ **Note:** This property is only read when the project starts. To change the physics FPS at runtime, set :ref:`Engine.physics_jitter_fix` instead. +\ **Note:** This property is only read when the project starts. To change the physics jitter fix at runtime, set :ref:`Engine.physics_jitter_fix` instead. .. rst-class:: classref-item-separator @@ -9642,7 +9682,7 @@ Base size used to determine size of froxel buffer in the camera X-axis and Y-axi .. rst-class:: classref-property -:ref:`String` **rendering/gl_compatibility/driver** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver** 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. @@ -9654,7 +9694,7 @@ Sets the driver to be used by the renderer when using the Compatibility renderer .. rst-class:: classref-property -:ref:`String` **rendering/gl_compatibility/driver.android** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver.android** Android override for :ref:`rendering/gl_compatibility/driver`. @@ -9666,7 +9706,7 @@ Android override for :ref:`rendering/gl_compatibility/driver` **rendering/gl_compatibility/driver.ios** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver.ios** iOS override for :ref:`rendering/gl_compatibility/driver`. @@ -9678,7 +9718,7 @@ iOS override for :ref:`rendering/gl_compatibility/driver` **rendering/gl_compatibility/driver.linuxbsd** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver.linuxbsd** LinuxBSD override for :ref:`rendering/gl_compatibility/driver`. @@ -9690,7 +9730,7 @@ LinuxBSD override for :ref:`rendering/gl_compatibility/driver` **rendering/gl_compatibility/driver.macos** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver.macos** macOS override for :ref:`rendering/gl_compatibility/driver`. @@ -9702,7 +9742,7 @@ macOS override for :ref:`rendering/gl_compatibility/driver` **rendering/gl_compatibility/driver.web** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver.web** Web override for :ref:`rendering/gl_compatibility/driver`. @@ -9714,7 +9754,7 @@ Web override for :ref:`rendering/gl_compatibility/driver` **rendering/gl_compatibility/driver.windows** = ``"opengl3"`` +:ref:`String` **rendering/gl_compatibility/driver.windows** Windows override for :ref:`rendering/gl_compatibility/driver`. @@ -9730,6 +9770,22 @@ Windows override for :ref:`rendering/gl_compatibility/driver`. +\ **Note:** This setting is implemented only on Windows. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ProjectSettings_property_rendering/gl_compatibility/fallback_to_native: + +.. rst-class:: classref-property + +:ref:`bool` **rendering/gl_compatibility/fallback_to_native** = ``true`` + +If ``true``, the compatibility renderer will fall back to native OpenGL if ANGLE over Metal is not supported. + +\ **Note:** This setting is implemented only on macOS. + .. rst-class:: classref-item-separator ---- @@ -9744,6 +9800,8 @@ An :ref:`Array` of devices which should always use the ANGLE render Each entry is a :ref:`Dictionary` with the following keys: ``vendor`` and ``name``. ``name`` can be set to ``*`` to add all devices with the specified ``vendor``. +\ **Note:** This setting is implemented only on Windows. + .. rst-class:: classref-item-separator ---- @@ -10556,7 +10614,7 @@ Override for :ref:`rendering/renderer/rendering_method` **rendering/rendering_device/driver** = ``"vulkan"`` +:ref:`String` **rendering/rendering_device/driver** 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. @@ -10568,7 +10626,7 @@ Sets the driver to be used by the renderer when using a RenderingDevice-based re .. rst-class:: classref-property -:ref:`String` **rendering/rendering_device/driver.android** = ``"vulkan"`` +:ref:`String` **rendering/rendering_device/driver.android** Android override for :ref:`rendering/rendering_device/driver`. @@ -10580,7 +10638,7 @@ Android override for :ref:`rendering/rendering_device/driver` **rendering/rendering_device/driver.ios** = ``"vulkan"`` +:ref:`String` **rendering/rendering_device/driver.ios** iOS override for :ref:`rendering/rendering_device/driver`. @@ -10592,7 +10650,7 @@ iOS override for :ref:`rendering/rendering_device/driver` **rendering/rendering_device/driver.linuxbsd** = ``"vulkan"`` +:ref:`String` **rendering/rendering_device/driver.linuxbsd** LinuxBSD override for :ref:`rendering/rendering_device/driver`. @@ -10604,7 +10662,7 @@ LinuxBSD override for :ref:`rendering/rendering_device/driver` **rendering/rendering_device/driver.macos** = ``"vulkan"`` +:ref:`String` **rendering/rendering_device/driver.macos** macOS override for :ref:`rendering/rendering_device/driver`. @@ -10616,7 +10674,7 @@ macOS override for :ref:`rendering/rendering_device/driver` **rendering/rendering_device/driver.windows** = ``"vulkan"`` +:ref:`String` **rendering/rendering_device/driver.windows** Windows override for :ref:`rendering/rendering_device/driver`. diff --git a/classes/class_randomnumbergenerator.rst b/classes/class_randomnumbergenerator.rst index b68edd4d749..ee5a5c9be94 100644 --- a/classes/class_randomnumbergenerator.rst +++ b/classes/class_randomnumbergenerator.rst @@ -213,7 +213,7 @@ Returns a pseudo-random 32-bit signed integer between ``from`` and ``to`` (inclu void **randomize** **(** **)** -Setups a time-based seed to for this **RandomNumberGenerator** instance. Unlike the :ref:`@GlobalScope` random number generation functions, different **RandomNumberGenerator** instances can use different seeds. +Sets up a time-based seed for this **RandomNumberGenerator** instance. Unlike the :ref:`@GlobalScope` random number generation functions, different **RandomNumberGenerator** instances can use different seeds. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_rect2.rst b/classes/class_rect2.rst index 2892e043973..82e576031db 100644 --- a/classes/class_rect2.rst +++ b/classes/class_rect2.rst @@ -520,7 +520,11 @@ Returns ``true`` if the :ref:`position` or :ref:` :ref:`Rect2` **operator *** **(** :ref:`Transform2D` right **)** -Inversely transforms (multiplies) the **Rect2** by the given :ref:`Transform2D` transformation matrix. +Inversely transforms (multiplies) the **Rect2** by the given :ref:`Transform2D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``rect * transform`` is equivalent to ``transform.inverse() * rect``. See :ref:`Transform2D.inverse`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * rect`` can be used instead. See :ref:`Transform2D.affine_inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_renderingdevice.rst b/classes/class_renderingdevice.rst index 97c169fee92..f55afd4f8f0 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -5362,7 +5362,7 @@ Once finished with your RID, you will want to free the RID using the RenderingDe :ref:`Error` **texture_clear** **(** :ref:`RID` texture, :ref:`Color` color, :ref:`int` base_mipmap, :ref:`int` mipmap_count, :ref:`int` base_layer, :ref:`int` layer_count, |bitfield|\<:ref:`BarrierMask`\> post_barrier=32767 **)** -Clears the specified ``texture`` by replacing all of its pixels with the specified ``color``. ``base_mipmap`` and ``mipmap_count`` determine which mipmaps of the texture are affected by this clear operation, while ``base_layer`` and ``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), ``base_layer`` and ``layer_count`` must both be ``0``. +Clears the specified ``texture`` by replacing all of its pixels with the specified ``color``. ``base_mipmap`` and ``mipmap_count`` determine which mipmaps of the texture are affected by this clear operation, while ``base_layer`` and ``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), ``base_layer`` must be ``0`` and ``layer_count`` must be ``1``. \ **Note:** ``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 :ref:`FINAL_ACTION_CONTINUE`) to clear this texture. diff --git a/classes/class_renderingserver.rst b/classes/class_renderingserver.rst index 40d83e29c5c..54fec469c18 100644 --- a/classes/class_renderingserver.rst +++ b/classes/class_renderingserver.rst @@ -1612,7 +1612,7 @@ Flag used to mark that the mesh does not have a vertex array and instead will in :ref:`ArrayFormat` **ARRAY_FLAG_COMPRESS_ATTRIBUTES** = ``536870912`` -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. .. _class_RenderingServer_constant_ARRAY_FLAG_FORMAT_VERSION_BASE: diff --git a/classes/class_resource.rst b/classes/class_resource.rst index 8703ce8ac57..b6bac257742 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -152,6 +152,8 @@ If ``true``, the resource is duplicated for each instance of all scenes using it 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. +\ **Note:** 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. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_richtextlabel.rst b/classes/class_richtextlabel.rst index a568037b105..62c8b0cb537 100644 --- a/classes/class_richtextlabel.rst +++ b/classes/class_richtextlabel.rst @@ -2054,7 +2054,7 @@ The vertical separation of elements in a table. :ref:`int` **text_highlight_h_padding** = ``3`` -The horizontal padding around a highlighting and background color box. +The horizontal padding around boxes drawn by the ``[fgcolor]`` and ``[bgcolor]`` tags. This does not affect the appearance of text selection. .. rst-class:: classref-item-separator @@ -2066,7 +2066,7 @@ The horizontal padding around a highlighting and background color box. :ref:`int` **text_highlight_v_padding** = ``3`` -The vertical padding around a highlighting and background color box. +The vertical padding around boxes drawn by the ``[fgcolor]`` and ``[bgcolor]`` tags. This does not affect the appearance of text selection. .. rst-class:: classref-item-separator diff --git a/classes/class_scrollbar.rst b/classes/class_scrollbar.rst index f6a7327bb66..30acc393f6c 100644 --- a/classes/class_scrollbar.rst +++ b/classes/class_scrollbar.rst @@ -64,8 +64,6 @@ Theme Properties +-----------------------------------+----------------------------------------------------------------------------+ | :ref:`StyleBox` | :ref:`grabber_pressed` | +-----------------------------------+----------------------------------------------------------------------------+ - | :ref:`StyleBox` | :ref:`hscroll` | - +-----------------------------------+----------------------------------------------------------------------------+ | :ref:`StyleBox` | :ref:`scroll` | +-----------------------------------+----------------------------------------------------------------------------+ | :ref:`StyleBox` | :ref:`scroll_focus` | @@ -227,20 +225,6 @@ Used when the grabber is being dragged. ---- -.. _class_ScrollBar_theme_style_hscroll: - -.. rst-class:: classref-themeproperty - -:ref:`StyleBox` **hscroll** - -.. container:: contribute - - There is currently no description for this theme property. Please help us by :ref:`contributing one `! - -.. rst-class:: classref-item-separator - ----- - .. _class_ScrollBar_theme_style_scroll: .. rst-class:: classref-themeproperty diff --git a/classes/class_tabbar.rst b/classes/class_tabbar.rst index ca8caa872f2..ea03bfa8993 100644 --- a/classes/class_tabbar.rst +++ b/classes/class_tabbar.rst @@ -297,7 +297,7 @@ Emitted when a tab is right-clicked. :ref:`select_with_rmb` tab **)** -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. .. rst-class:: classref-section-separator diff --git a/classes/class_tabcontainer.rst b/classes/class_tabcontainer.rst index ce265e63f92..7265cd9fe47 100644 --- a/classes/class_tabcontainer.rst +++ b/classes/class_tabcontainer.rst @@ -263,7 +263,7 @@ Emitted when a tab is hovered by the mouse. **tab_selected** **(** :ref:`int` tab **)** -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. .. rst-class:: classref-section-separator diff --git a/classes/class_time.rst b/classes/class_time.rst index 377ead4f322..e9717ca618b 100644 --- a/classes/class_time.rst +++ b/classes/class_time.rst @@ -507,7 +507,11 @@ Converts the given Unix timestamp to an ISO 8601 time string (HH:MM:SS). :ref:`Dictionary` **get_time_zone_from_system** **(** **)** |const| -Returns the current time zone as a dictionary of keys: ``bias`` and ``name``. The ``bias`` 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: ``bias`` and ``name``. + +- ``bias`` is the offset from UTC in minutes, since not all time zones are multiples of an hour from UTC. + +- ``name`` is the localized name of the time zone, according to the OS locale settings of the current user. .. rst-class:: classref-item-separator diff --git a/classes/class_transform2d.rst b/classes/class_transform2d.rst index 56c73be75db..cc9eb73dccc 100644 --- a/classes/class_transform2d.rst +++ b/classes/class_transform2d.rst @@ -300,7 +300,7 @@ Method Descriptions :ref:`Transform2D` **affine_inverse** **(** **)** |const| -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). .. rst-class:: classref-item-separator @@ -314,7 +314,7 @@ Returns the inverse of the transform, under the assumption that the transformati 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 :ref:`origin` vector). .. rst-class:: classref-item-separator @@ -326,9 +326,13 @@ This method does not account for translation (the origin vector). :ref:`Vector2` **basis_xform_inv** **(** :ref:`Vector2` v **)** |const| -Returns a vector transformed (multiplied) by the inverse basis matrix. +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 origin vector). +This method does not account for translation (the :ref:`origin` vector). + +\ ``transform.basis_xform_inv(vector)`` is equivalent to ``transform.inverse().basis_xform(vector)``. See :ref:`inverse`. + +For non-orthonormal transforms (e.g. with scaling) ``transform.affine_inverse().basis_xform(vector)`` can be used instead. See :ref:`affine_inverse`. .. rst-class:: classref-item-separator @@ -414,7 +418,7 @@ Returns a transform interpolated between this transform and another by a given ` :ref:`Transform2D` **inverse** **(** **)** |const| -Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use :ref:`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 :ref:`affine_inverse` for non-orthonormal transforms (e.g. with scaling). .. rst-class:: classref-item-separator @@ -651,7 +655,7 @@ Transforms (multiplies) the :ref:`Vector2` by the given **Transfo :ref:`Transform2D` **operator *** **(** :ref:`float` right **)** -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 :ref:`origin` vector, which scales it uniformly. .. rst-class:: classref-item-separator @@ -663,7 +667,7 @@ This operator multiplies all components of the **Transform2D**, including the or :ref:`Transform2D` **operator *** **(** :ref:`int` right **)** -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 :ref:`origin` vector, which scales it uniformly. .. rst-class:: classref-item-separator diff --git a/classes/class_transform3d.rst b/classes/class_transform3d.rst index 0e3b350a94d..68eb7cf7079 100644 --- a/classes/class_transform3d.rst +++ b/classes/class_transform3d.rst @@ -282,7 +282,7 @@ Method Descriptions :ref:`Transform3D` **affine_inverse** **(** **)** |const| -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). .. rst-class:: classref-item-separator @@ -306,7 +306,7 @@ Returns a transform interpolated between this transform and another by a given ` :ref:`Transform3D` **inverse** **(** **)** |const| -Returns the inverse of the transform, under the assumption that the transformation is composed of rotation and translation (no scaling, use :ref:`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 :ref:`affine_inverse` for non-orthonormal transforms (e.g. with scaling). .. rst-class:: classref-item-separator @@ -549,7 +549,7 @@ Transforms (multiplies) the :ref:`Vector3` by the given **Transfo :ref:`Transform3D` **operator *** **(** :ref:`float` right **)** -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 :ref:`origin` vector, which scales it uniformly. .. rst-class:: classref-item-separator @@ -561,7 +561,7 @@ This operator multiplies all components of the **Transform3D**, including the or :ref:`Transform3D` **operator *** **(** :ref:`int` right **)** -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 :ref:`origin` vector, which scales it uniformly. .. rst-class:: classref-item-separator diff --git a/classes/class_vector2.rst b/classes/class_vector2.rst index 5f387648ef1..f3c098c8578 100644 --- a/classes/class_vector2.rst +++ b/classes/class_vector2.rst @@ -951,7 +951,11 @@ Returns ``true`` if the vectors are not equal. :ref:`Vector2` **operator *** **(** :ref:`Transform2D` right **)** -Inversely transforms (multiplies) the **Vector2** by the given :ref:`Transform2D` transformation matrix. +Inversely transforms (multiplies) the **Vector2** by the given :ref:`Transform2D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``vector * transform`` is equivalent to ``transform.inverse() * vector``. See :ref:`Transform2D.inverse`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * vector`` can be used instead. See :ref:`Transform2D.affine_inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_vector3.rst b/classes/class_vector3.rst index 73ba23f1588..39304e75695 100644 --- a/classes/class_vector3.rst +++ b/classes/class_vector3.rst @@ -1023,7 +1023,11 @@ Returns ``true`` if the vectors are not equal. :ref:`Vector3` **operator *** **(** :ref:`Basis` right **)** -Inversely transforms (multiplies) the **Vector3** by the given :ref:`Basis` matrix. +Inversely transforms (multiplies) the **Vector3** by the given :ref:`Basis` matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``vector * basis`` is equivalent to ``basis.transposed() * vector``. See :ref:`Basis.transposed`. + +For transforming by inverse of a non-orthonormal basis (e.g. with scaling) ``basis.inverse() * vector`` can be used instead. See :ref:`Basis.inverse`. .. rst-class:: classref-item-separator @@ -1037,6 +1041,8 @@ Inversely transforms (multiplies) the **Vector3** by the given :ref:`Basis`. +\ ``vector * quaternion`` is equivalent to ``quaternion.inverse() * vector``. See :ref:`Quaternion.inverse`. + .. rst-class:: classref-item-separator ---- @@ -1047,7 +1053,11 @@ Inversely transforms (multiplies) the **Vector3** by the given :ref:`Quaternion< :ref:`Vector3` **operator *** **(** :ref:`Transform3D` right **)** -Inversely transforms (multiplies) the **Vector3** by the given :ref:`Transform3D` transformation matrix. +Inversely transforms (multiplies) the **Vector3** by the given :ref:`Transform3D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``vector * transform`` is equivalent to ``transform.inverse() * vector``. See :ref:`Transform3D.inverse`. + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * vector`` can be used instead. See :ref:`Transform3D.affine_inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_vector4.rst b/classes/class_vector4.rst index 8866fc051a7..42f97b0b1b6 100644 --- a/classes/class_vector4.rst +++ b/classes/class_vector4.rst @@ -692,7 +692,9 @@ Returns ``true`` if the vectors are not equal. :ref:`Vector4` **operator *** **(** :ref:`Projection` right **)** -Inversely transforms (multiplies) the **Vector4** by the given :ref:`Projection` matrix. +Transforms (multiplies) the **Vector4** by the transpose of the given :ref:`Projection` matrix. + +For transforming by inverse of a projection ``projection.inverse() * vector`` can be used instead. See :ref:`Projection.inverse`. .. rst-class:: classref-item-separator diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index ed482a8e63e..00d5f59346b 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -75,8 +75,6 @@ Properties +-----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------+----------------+ | :ref:`DebugDraw` | :ref:`debug_draw` | ``0`` | +-----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------+----------------+ - | :ref:`bool` | :ref:`disable_2d` | ``false`` | - +-----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------+----------------+ | :ref:`bool` | :ref:`disable_3d` | ``false`` | +-----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------+----------------+ | :ref:`float` | :ref:`fsr_sharpness` | ``0.2`` | @@ -1108,23 +1106,6 @@ The overlay mode for test rendered geometry in debug purposes. ---- -.. _class_Viewport_property_disable_2d: - -.. rst-class:: classref-property - -:ref:`bool` **disable_2d** = ``false`` - -.. rst-class:: classref-property-setget - -- void **set_disable_2d** **(** :ref:`bool` value **)** -- :ref:`bool` **is_2d_disabled** **(** **)** - -If ``true``, disables 2D rendering while keeping 3D rendering. See also :ref:`disable_3d`. - -.. rst-class:: classref-item-separator - ----- - .. _class_Viewport_property_disable_3d: .. rst-class:: classref-property @@ -1136,7 +1117,7 @@ If ``true``, disables 2D rendering while keeping 3D rendering. See also :ref:`di - void **set_disable_3d** **(** :ref:`bool` value **)** - :ref:`bool` **is_3d_disabled** **(** **)** -If ``true``, disables 3D rendering while keeping 2D rendering. See also :ref:`disable_2d`. +Disable 3D rendering (but keep 2D rendering). .. rst-class:: classref-item-separator diff --git a/classes/class_visibleonscreenenabler2d.rst b/classes/class_visibleonscreenenabler2d.rst index e6cf8369433..0b7e6354225 100644 --- a/classes/class_visibleonscreenenabler2d.rst +++ b/classes/class_visibleonscreenenabler2d.rst @@ -12,14 +12,18 @@ VisibleOnScreenEnabler2D **Inherits:** :ref:`VisibleOnScreenNotifier2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Automatically disables another node if not visible on screen. +A rectangular region of 2D space that, when visible on screen, enables a target node. .. rst-class:: classref-introduction-group Description ----------- -VisibleOnScreenEnabler2D detects when it is visible on screen (just like :ref:`VisibleOnScreenNotifier2D`) and automatically enables or disables the target node. The target node is disabled when **VisibleOnScreenEnabler2D** is not visible on screen (including when :ref:`CanvasItem.visible` is ``false``), and enabled when the enabler is visible. The disabling is achieved by changing :ref:`Node.process_mode`. +**VisibleOnScreenEnabler2D** contains a rectangular region of 2D space and a target node. The target node will be automatically enabled (via its :ref:`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 :ref:`VisibleOnScreenNotifier2D` if you only want to be notified when the region is visible on screen. + +\ **Note:** **VisibleOnScreenEnabler2D** uses the render culling code to determine whether it's visible on screen, so it won't function unless :ref:`CanvasItem.visible` is set to ``true``. .. rst-class:: classref-reftable-group @@ -94,7 +98,7 @@ Property Descriptions - void **set_enable_mode** **(** :ref:`EnableMode` value **)** - :ref:`EnableMode` **get_enable_mode** **(** **)** -Determines how the node is enabled. Corresponds to :ref:`ProcessMode`. Disabled node uses :ref:`Node.PROCESS_MODE_DISABLED`. +Determines how the target node is enabled. Corresponds to :ref:`ProcessMode`. When the node is disabled, it always uses :ref:`Node.PROCESS_MODE_DISABLED`. .. rst-class:: classref-item-separator @@ -111,7 +115,7 @@ Determines how the node is enabled. Corresponds to :ref:`ProcessMode` value **)** - :ref:`NodePath` **get_enable_node_path** **(** **)** -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. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_visibleonscreenenabler3d.rst b/classes/class_visibleonscreenenabler3d.rst index 814b032390a..a10caf07f74 100644 --- a/classes/class_visibleonscreenenabler3d.rst +++ b/classes/class_visibleonscreenenabler3d.rst @@ -12,20 +12,18 @@ VisibleOnScreenEnabler3D **Inherits:** :ref:`VisibleOnScreenNotifier3D` **<** :ref:`VisualInstance3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Enables certain nodes only when approximately visible. +A box-shaped region of 3D space that, when visible on screen, enables a target node. .. rst-class:: classref-introduction-group Description ----------- -The VisibleOnScreenEnabler3D will disable :ref:`RigidBody3D` and :ref:`AnimationPlayer` nodes when they are not visible. It will only affect other nodes within the same scene as the VisibleOnScreenEnabler3D itself. +**VisibleOnScreenEnabler3D** contains a box-shaped region of 3D space and a target node. The target node will be automatically enabled (via its :ref:`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. -If you just want to receive notifications, use :ref:`VisibleOnScreenNotifier3D` instead. +See :ref:`VisibleOnScreenNotifier3D` if you only want to be notified when the region is visible on screen. -\ **Note:** 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 :ref:`Area3D` node as a child of a :ref:`Camera3D` node and/or :ref:`Vector3.dot`. - -\ **Note:** VisibleOnScreenEnabler3D will not affect nodes added after scene initialization. +\ **Note:** **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 :ref:`Node3D.visible` is set to ``true``. .. rst-class:: classref-reftable-group @@ -62,7 +60,7 @@ enum **EnableMode**: :ref:`EnableMode` **ENABLE_MODE_INHERIT** = ``0`` - +Corresponds to :ref:`Node.PROCESS_MODE_INHERIT`. .. _class_VisibleOnScreenEnabler3D_constant_ENABLE_MODE_ALWAYS: @@ -70,7 +68,7 @@ enum **EnableMode**: :ref:`EnableMode` **ENABLE_MODE_ALWAYS** = ``1`` - +Corresponds to :ref:`Node.PROCESS_MODE_ALWAYS`. .. _class_VisibleOnScreenEnabler3D_constant_ENABLE_MODE_WHEN_PAUSED: @@ -78,7 +76,7 @@ enum **EnableMode**: :ref:`EnableMode` **ENABLE_MODE_WHEN_PAUSED** = ``2`` - +Corresponds to :ref:`Node.PROCESS_MODE_WHEN_PAUSED`. .. rst-class:: classref-section-separator @@ -100,9 +98,7 @@ Property Descriptions - void **set_enable_mode** **(** :ref:`EnableMode` value **)** - :ref:`EnableMode` **get_enable_mode** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Determines how the target node is enabled. Corresponds to :ref:`ProcessMode`. When the node is disabled, it always uses :ref:`Node.PROCESS_MODE_DISABLED`. .. rst-class:: classref-item-separator @@ -119,9 +115,7 @@ Property Descriptions - void **set_enable_node_path** **(** :ref:`NodePath` value **)** - :ref:`NodePath` **get_enable_node_path** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +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. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_visibleonscreennotifier2d.rst b/classes/class_visibleonscreennotifier2d.rst index e51e708ff18..70fae8f0206 100644 --- a/classes/class_visibleonscreennotifier2d.rst +++ b/classes/class_visibleonscreennotifier2d.rst @@ -14,18 +14,18 @@ VisibleOnScreenNotifier2D **Inherited By:** :ref:`VisibleOnScreenEnabler2D` -Detects when the node extents are visible on screen. +A rectangular region of 2D space that detects whether it is visible on screen. .. rst-class:: classref-introduction-group 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. +:ref:`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 :ref:`screen_entered` signal, and likewise it will emit a :ref:`screen_exited` signal when no part of it remains visible. -If you want nodes to be disabled automatically when they exit the screen, use :ref:`VisibleOnScreenEnabler2D` instead. +If you want a node to be enabled automatically when this region is visible on screen, use :ref:`VisibleOnScreenEnabler2D`. -\ **Note:** VisibleOnScreenNotifier2D uses the render culling code to determine whether it's visible on screen, which also means that its :ref:`CanvasItem.visible` must be ``true`` to work correctly. +\ **Note:** **VisibleOnScreenNotifier2D** uses the render culling code to determine whether it's visible on screen, so it won't function unless :ref:`CanvasItem.visible` is set to ``true``. .. rst-class:: classref-introduction-group @@ -126,7 +126,7 @@ Method Descriptions If ``true``, the bounding rectangle is on the screen. -\ **Note:** It takes one frame for the node's visibility to be assessed once added to the scene tree, so this method will return ``false`` right after it is instantiated, even if it will be on screen in the draw pass. +\ **Note:** It takes one frame for the **VisibleOnScreenNotifier2D**'s visibility to be determined once added to the scene tree, so this method will always return ``false`` right after it is instantiated, before the draw pass. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` diff --git a/classes/class_visibleonscreennotifier3d.rst b/classes/class_visibleonscreennotifier3d.rst index 419d2b22306..529fba91d90 100644 --- a/classes/class_visibleonscreennotifier3d.rst +++ b/classes/class_visibleonscreennotifier3d.rst @@ -14,18 +14,18 @@ VisibleOnScreenNotifier3D **Inherited By:** :ref:`VisibleOnScreenEnabler3D` -Detects approximately when the node is visible on screen. +A box-shaped region of 3D space that detects whether it is visible on screen. .. rst-class:: classref-introduction-group 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 :ref:`Camera3D`'s view. +:ref:`VisibleOnScreenEnabler3D` represents a box-shaped region of 3D space. When any part of this region becomes visible on screen or in a :ref:`Camera3D`'s view, it will emit a :ref:`screen_entered` signal, and likewise it will emit a :ref:`screen_exited` signal when no part of it remains visible. -If you want nodes to be disabled automatically when they exit the screen, use :ref:`VisibleOnScreenEnabler3D` instead. +If you want a node to be enabled automatically when this region is visible on screen, use :ref:`VisibleOnScreenEnabler3D`. -\ **Note:** VisibleOnScreenNotifier3D uses the render culling code to determine whether it's visible on screen, which also means that its :ref:`Node3D.visible` must be ``true`` to work correctly. +\ **Note:** **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 :ref:`Node3D.visible` is set to ``true``. .. rst-class:: classref-reftable-group @@ -66,7 +66,7 @@ Signals **screen_entered** **(** **)** -Emitted when the VisibleOnScreenNotifier3D enters the screen. +Emitted when the **VisibleOnScreenNotifier3D** enters the screen. .. rst-class:: classref-item-separator @@ -78,7 +78,7 @@ Emitted when the VisibleOnScreenNotifier3D enters the screen. **screen_exited** **(** **)** -Emitted when the VisibleOnScreenNotifier3D exits the screen. +Emitted when the **VisibleOnScreenNotifier3D** exits the screen. .. rst-class:: classref-section-separator @@ -100,7 +100,7 @@ Property Descriptions - void **set_aabb** **(** :ref:`AABB` value **)** - :ref:`AABB` **get_aabb** **(** **)** -The VisibleOnScreenNotifier3D's bounding box. +The **VisibleOnScreenNotifier3D**'s bounding box. .. rst-class:: classref-section-separator @@ -117,9 +117,9 @@ Method Descriptions :ref:`bool` **is_on_screen** **(** **)** |const| -If ``true``, the bounding box is on the screen. +Returns ``true`` if the bounding box is on the screen. -\ **Note:** It takes one frame for the node's visibility to be assessed once added to the scene tree, so this method will return ``false`` right after it is instantiated, even if it will be on screen in the draw pass. +\ **Note:** It takes one frame for the **VisibleOnScreenNotifier3D**'s visibility to be assessed once added to the scene tree, so this method will always return ``false`` right after it is instantiated. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`