From f9340bddb2413a7db6779ddc70a2acf9904da187 Mon Sep 17 00:00:00 2001 From: Godot Organization Date: Sat, 3 Jun 2023 03:19:05 +0000 Subject: [PATCH] classref: Sync with current master branch (543750a) --- classes/class_@gdscript.rst | 4 +- classes/class_@globalscope.rst | 6 +- classes/class_aabb.rst | 2 +- classes/class_acceptdialog.rst | 4 +- classes/class_aescontext.rst | 4 +- classes/class_animatablebody2d.rst | 8 +- classes/class_animatablebody3d.rst | 10 +- classes/class_animationnode.rst | 34 ++--- classes/class_animationnodeadd2.rst | 6 +- classes/class_animationnodeadd3.rst | 10 +- classes/class_animationnodeblend2.rst | 4 +- classes/class_animationnodeblend3.rst | 12 +- classes/class_animationnodeblendspace1d.rst | 2 +- classes/class_animationnodeblendspace2d.rst | 2 +- classes/class_animationnodeblendtree.rst | 22 +-- classes/class_animationnodeoneshot.rst | 8 +- classes/class_animationnodestatemachine.rst | 20 +-- ...lass_animationnodestatemachineplayback.rst | 2 +- classes/class_animationnodesub2.rst | 42 ++++++ classes/class_animationnodesync.rst | 2 +- classes/class_animationnodetimeseek.rst | 2 +- classes/class_animationnodetransition.rst | 4 +- classes/class_animationplayer.rst | 2 + classes/class_animationrootnode.rst | 2 + classes/class_area2d.rst | 8 +- classes/class_area3d.rst | 12 +- classes/class_array.rst | 6 +- classes/class_arrayoccluder3d.rst | 12 +- classes/class_aspectratiocontainer.rst | 6 +- classes/class_astar2d.rst | 10 +- classes/class_astar3d.rst | 6 +- classes/class_astargrid2d.rst | 8 +- .../class_audiostreamplaybackpolyphonic.rst | 2 +- classes/class_basebutton.rst | 4 +- classes/class_basis.rst | 10 +- classes/class_bool.rst | 92 +++--------- classes/class_boxcontainer.rst | 6 +- classes/class_boxshape3d.rst | 6 +- classes/class_button.rst | 8 +- classes/class_buttongroup.rst | 6 +- classes/class_callable.rst | 2 +- classes/class_camera3d.rst | 12 +- classes/class_canvasitem.rst | 14 +- classes/class_canvaslayer.rst | 10 +- classes/class_canvasmodulate.rst | 4 +- classes/class_capsuleshape2d.rst | 6 +- classes/class_capsuleshape3d.rst | 6 +- classes/class_centercontainer.rst | 6 +- classes/class_characterbody2d.rst | 8 +- classes/class_characterbody3d.rst | 10 +- classes/class_checkbox.rst | 6 +- classes/class_checkbutton.rst | 4 +- classes/class_circleshape2d.rst | 6 +- classes/class_classdb.rst | 2 +- classes/class_codeedit.rst | 6 +- classes/class_codehighlighter.rst | 4 +- classes/class_collisionobject2d.rst | 4 +- classes/class_collisionobject3d.rst | 6 +- classes/class_collisionpolygon2d.rst | 8 +- classes/class_collisionpolygon3d.rst | 8 +- classes/class_collisionshape2d.rst | 6 +- classes/class_collisionshape3d.rst | 8 +- classes/class_color.rst | 16 +-- classes/class_colorpicker.rst | 6 +- classes/class_colorpickerbutton.rst | 4 +- classes/class_colorrect.rst | 19 +-- classes/class_concavepolygonshape2d.rst | 16 +-- classes/class_concavepolygonshape3d.rst | 16 +-- classes/class_conetwistjoint3d.rst | 8 +- classes/class_confirmationdialog.rst | 4 +- classes/class_container.rst | 8 +- classes/class_control.rst | 6 +- classes/class_convexpolygonshape2d.rst | 12 +- classes/class_convexpolygonshape3d.rst | 12 +- classes/class_crypto.rst | 6 +- classes/class_cylindershape3d.rst | 6 +- classes/class_dampedspringjoint2d.rst | 4 +- classes/class_dictionary.rst | 16 +-- classes/class_diraccess.rst | 6 +- classes/class_displayserver.rst | 132 +++++++++--------- classes/class_editorfiledialog.rst | 2 +- classes/class_editorimportplugin.rst | 8 +- classes/class_editorinterface.rst | 2 +- classes/class_editornode3dgizmoplugin.rst | 2 +- classes/class_editorproperty.rst | 4 +- classes/class_editorresourcepreview.rst | 4 +- classes/class_editorresourcetooltipplugin.rst | 38 +++-- classes/class_editorsettings.rst | 30 +--- classes/class_editorsyntaxhighlighter.rst | 4 +- classes/class_engine.rst | 2 +- classes/class_fileaccess.rst | 23 +-- classes/class_filedialog.rst | 4 +- classes/class_filesystemdock.rst | 4 +- classes/class_float.rst | 20 ++- classes/class_flowcontainer.rst | 11 +- classes/class_font.rst | 4 +- classes/class_fontfile.rst | 6 +- classes/class_fontvariation.rst | 4 +- classes/class_generic6dofjoint3d.rst | 6 +- classes/class_geometry2d.rst | 4 +- classes/class_geometry3d.rst | 4 +- classes/class_gltfstate.rst | 20 ++- classes/class_gradient.rst | 71 ++++++++-- classes/class_gradienttexture2d.rst | 8 ++ classes/class_graphedit.rst | 8 +- classes/class_graphnode.rst | 10 +- classes/class_gridcontainer.rst | 10 +- classes/class_groovejoint2d.rst | 4 +- classes/class_hashingcontext.rst | 4 +- classes/class_hboxcontainer.rst | 6 +- classes/class_heightmapshape3d.rst | 6 +- classes/class_hflowcontainer.rst | 11 +- classes/class_hingejoint3d.rst | 4 +- classes/class_hscrollbar.rst | 4 +- classes/class_hseparator.rst | 4 +- classes/class_hslider.rst | 6 +- classes/class_hsplitcontainer.rst | 6 +- classes/class_httpclient.rst | 2 +- classes/class_httprequest.rst | 8 +- classes/class_input.rst | 10 +- classes/class_inputevent.rst | 6 +- classes/class_inputeventaction.rst | 6 +- classes/class_inputeventfromwindow.rst | 2 +- classes/class_inputeventgesture.rst | 11 +- classes/class_inputeventjoypadbutton.rst | 4 +- classes/class_inputeventjoypadmotion.rst | 6 +- classes/class_inputeventkey.rst | 8 +- classes/class_inputeventmagnifygesture.rst | 13 +- classes/class_inputeventmidi.rst | 4 +- classes/class_inputeventmouse.rst | 4 +- classes/class_inputeventmousebutton.rst | 6 +- classes/class_inputeventmousemotion.rst | 6 +- classes/class_inputeventpangesture.rst | 11 +- classes/class_inputeventscreendrag.rst | 6 +- classes/class_inputeventscreentouch.rst | 8 +- classes/class_inputeventshortcut.rst | 4 +- classes/class_inputeventwithmodifiers.rst | 6 +- classes/class_inputmap.rst | 4 +- classes/class_int.rst | 2 +- classes/class_itemlist.rst | 8 +- classes/class_javascriptobject.rst | 2 +- classes/class_joint2d.rst | 4 +- classes/class_joint3d.rst | 4 +- classes/class_kinematiccollision2d.rst | 6 +- classes/class_kinematiccollision3d.rst | 6 +- classes/class_label.rst | 6 +- classes/class_label3d.rst | 4 +- classes/class_labelsettings.rst | 4 +- classes/class_lineedit.rst | 22 ++- classes/class_linkbutton.rst | 4 +- classes/class_margincontainer.rst | 8 +- classes/class_menubar.rst | 4 +- classes/class_menubutton.rst | 6 +- classes/class_mesh.rst | 8 +- classes/class_missingnode.rst | 6 +- classes/class_missingresource.rst | 6 +- classes/class_mutex.rst | 16 ++- classes/class_navigationagent2d.rst | 8 +- classes/class_navigationagent3d.rst | 8 +- classes/class_navigationlink2d.rst | 4 +- classes/class_navigationlink3d.rst | 4 +- classes/class_navigationmesh.rst | 2 +- .../class_navigationpathqueryparameters2d.rst | 4 +- .../class_navigationpathqueryparameters3d.rst | 4 +- classes/class_navigationpathqueryresult2d.rst | 4 +- classes/class_navigationpathqueryresult3d.rst | 4 +- classes/class_navigationpolygon.rst | 2 +- classes/class_navigationregion2d.rst | 6 +- classes/class_navigationregion3d.rst | 4 +- classes/class_navigationserver2d.rst | 12 +- classes/class_navigationserver3d.rst | 10 +- classes/class_ninepatchrect.rst | 4 +- classes/class_node.rst | 2 +- classes/class_nodepath.rst | 4 +- classes/class_noisetexture2d.rst | 18 +-- classes/class_noisetexture3d.rst | 10 +- classes/class_object.rst | 14 +- classes/class_optimizedtranslation.rst | 4 +- classes/class_optionbutton.rst | 8 +- classes/class_os.rst | 8 +- classes/class_packeddatacontainerref.rst | 2 +- classes/class_packedfloat32array.rst | 12 ++ classes/class_packedfloat64array.rst | 12 ++ classes/class_packedvector2array.rst | 12 ++ classes/class_packedvector3array.rst | 12 ++ classes/class_panel.rst | 6 +- classes/class_panelcontainer.rst | 6 +- classes/class_parallaxbackground.rst | 2 + classes/class_physicsbody2d.rst | 4 +- classes/class_physicsbody3d.rst | 6 +- classes/class_physicsdirectbodystate2d.rst | 4 +- ...lass_physicsdirectbodystate2dextension.rst | 11 +- classes/class_physicsdirectbodystate3d.rst | 4 +- ...lass_physicsdirectbodystate3dextension.rst | 11 +- classes/class_physicsdirectspacestate2d.rst | 4 +- ...ass_physicsdirectspacestate2dextension.rst | 11 +- classes/class_physicsdirectspacestate3d.rst | 4 +- ...ass_physicsdirectspacestate3dextension.rst | 11 +- classes/class_physicsmaterial.rst | 4 +- .../class_physicspointqueryparameters2d.rst | 4 +- .../class_physicspointqueryparameters3d.rst | 4 +- classes/class_physicsrayqueryparameters2d.rst | 4 +- classes/class_physicsrayqueryparameters3d.rst | 4 +- classes/class_physicsserver2d.rst | 8 +- classes/class_physicsserver2dextension.rst | 11 +- classes/class_physicsserver2dmanager.rst | 4 +- classes/class_physicsserver3d.rst | 18 ++- classes/class_physicsserver3dextension.rst | 11 +- classes/class_physicsserver3dmanager.rst | 4 +- ..._physicsserver3drenderingserverhandler.rst | 4 +- .../class_physicsshapequeryparameters2d.rst | 4 +- .../class_physicsshapequeryparameters3d.rst | 4 +- .../class_physicstestmotionparameters2d.rst | 4 +- .../class_physicstestmotionparameters3d.rst | 4 +- classes/class_physicstestmotionresult2d.rst | 4 +- classes/class_physicstestmotionresult3d.rst | 4 +- classes/class_pinjoint2d.rst | 4 +- classes/class_pinjoint3d.rst | 4 +- classes/class_plane.rst | 4 +- classes/class_popup.rst | 4 +- classes/class_popupmenu.rst | 10 +- classes/class_popuppanel.rst | 6 +- classes/class_progressbar.rst | 4 +- classes/class_projection.rst | 4 +- classes/class_projectsettings.rst | 46 +++++- classes/class_randomnumbergenerator.rst | 10 +- classes/class_range.rst | 16 +-- classes/class_raycast2d.rst | 12 +- classes/class_raycast3d.rst | 12 +- classes/class_rect2.rst | 2 +- classes/class_rect2i.rst | 2 +- classes/class_rectangleshape2d.rst | 6 +- classes/class_referencerect.rst | 6 +- classes/class_renderingdevice.rst | 2 +- classes/class_renderingserver.rst | 8 +- classes/class_resource.rst | 4 +- classes/class_resourceimporter.rst | 4 +- classes/class_resourceloader.rst | 4 +- classes/class_resourcepreloader.rst | 2 +- classes/class_resourcesaver.rst | 6 +- classes/class_resourceuid.rst | 8 +- classes/class_richtexteffect.rst | 4 +- classes/class_richtextlabel.rst | 8 +- classes/class_rid.rst | 2 +- classes/class_rigidbody2d.rst | 12 +- classes/class_rigidbody3d.rst | 10 +- classes/class_scenestate.rst | 4 +- classes/class_scriptcreatedialog.rst | 2 +- classes/class_scripteditor.rst | 4 +- classes/class_scripteditorbase.rst | 2 +- classes/class_scrollbar.rst | 4 +- classes/class_scrollcontainer.rst | 10 +- classes/class_segmentshape2d.rst | 6 +- classes/class_semaphore.rst | 14 +- classes/class_separationrayshape2d.rst | 6 +- classes/class_separationrayshape3d.rst | 6 +- classes/class_separator.rst | 4 +- classes/class_shape2d.rst | 6 +- classes/class_shape3d.rst | 6 +- classes/class_shapecast2d.rst | 10 +- classes/class_shapecast3d.rst | 10 +- classes/class_signal.rst | 2 +- classes/class_skeleton3d.rst | 6 +- classes/class_slider.rst | 6 +- classes/class_sliderjoint3d.rst | 4 +- classes/class_softbody3d.rst | 6 +- classes/class_sphereshape3d.rst | 6 +- classes/class_spinbox.rst | 4 +- classes/class_splitcontainer.rst | 6 +- classes/class_springarm3d.rst | 10 +- classes/class_staticbody2d.rst | 12 +- classes/class_staticbody3d.rst | 14 +- classes/class_streampeer.rst | 8 +- classes/class_streampeerbuffer.rst | 4 +- classes/class_streampeergzip.rst | 4 +- classes/class_streampeertcp.rst | 4 +- classes/class_streampeertls.rst | 4 +- classes/class_string.rst | 4 +- classes/class_stringname.rst | 10 +- classes/class_stylebox.rst | 6 +- classes/class_styleboxempty.rst | 4 +- classes/class_styleboxflat.rst | 12 +- classes/class_styleboxline.rst | 4 +- classes/class_styleboxtexture.rst | 4 +- classes/class_subviewport.rst | 6 +- classes/class_subviewportcontainer.rst | 8 +- classes/class_surfacetool.rst | 4 +- classes/class_syntaxhighlighter.rst | 8 +- classes/class_systemfont.rst | 6 +- classes/class_tabbar.rst | 4 +- classes/class_tabcontainer.rst | 10 +- classes/class_textedit.rst | 4 +- classes/class_textline.rst | 2 +- classes/class_textparagraph.rst | 2 +- classes/class_textserver.rst | 6 +- classes/class_textserveradvanced.rst | 9 +- classes/class_textserverextension.rst | 4 +- classes/class_textserverfallback.rst | 11 +- classes/class_textservermanager.rst | 12 +- classes/class_texturebutton.rst | 2 +- classes/class_texturerect.rst | 4 +- classes/class_theme.rst | 4 +- classes/class_themedb.rst | 4 +- classes/class_thread.rst | 2 +- classes/class_time.rst | 2 +- classes/class_transform2d.rst | 4 +- classes/class_transform3d.rst | 4 +- classes/class_translation.rst | 4 +- classes/class_translationserver.rst | 18 +-- classes/class_tree.rst | 6 +- classes/class_treeitem.rst | 26 +++- classes/class_undoredo.rst | 10 +- classes/class_variant.rst | 5 +- classes/class_vboxcontainer.rst | 6 +- classes/class_vector2.rst | 16 ++- classes/class_vector2i.rst | 4 +- classes/class_vector3.rst | 16 ++- classes/class_vector3i.rst | 4 +- classes/class_vector4.rst | 16 ++- classes/class_vector4i.rst | 6 +- classes/class_vehiclebody3d.rst | 10 +- classes/class_vehiclewheel3d.rst | 6 +- classes/class_vflowcontainer.rst | 11 +- classes/class_videostreamplayer.rst | 4 +- classes/class_viewport.rst | 22 ++- classes/class_viewporttexture.rst | 12 +- classes/class_visualinstance3d.rst | 4 + classes/class_vscrollbar.rst | 4 +- classes/class_vseparator.rst | 4 +- classes/class_vslider.rst | 6 +- classes/class_vsplitcontainer.rst | 6 +- classes/class_weakref.rst | 4 +- classes/class_window.rst | 42 ++++-- classes/class_world2d.rst | 4 +- classes/class_world3d.rst | 4 +- classes/class_worldboundaryshape2d.rst | 6 +- classes/class_worldboundaryshape3d.rst | 6 +- classes/class_xmlparser.rst | 4 +- classes/class_zippacker.rst | 6 +- classes/index.rst | 1 + 340 files changed, 1505 insertions(+), 1258 deletions(-) create mode 100644 classes/class_animationnodesub2.rst diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 5b50257c835..b02122829b2 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -10,7 +10,7 @@ @GDScript ========= -Built-in GDScript functions. +Built-in GDScript constants, functions, and annotations. .. rst-class:: classref-introduction-group @@ -109,7 +109,7 @@ Positive floating-point infinity. This is the result of floating-point division **NAN** = ``nan`` -"Not a Number", an invalid floating-point value. :ref:`NAN` has special properties, including that it is not equal to itself (``NAN == NAN`` returns ``false``). It is output by some invalid operations, such as dividing floating-point ``0.0`` by ``0.0``. +"Not a Number", an invalid floating-point value. :ref:`NAN` has special properties, including that ``!=`` always returns ``true``, while other comparison operators always return ``false``. This is true even when comparing with itself (``NAN == NAN`` returns ``false`` and ``NAN != NAN`` returns ``true``). It is returned by some invalid operations, such as dividing floating-point ``0.0`` by ``0.0``. \ **Warning:** "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer ``0`` by ``0`` will not result in :ref:`NAN` and will result in a run-time error instead. diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 26b8db1cf37..1d6c8cb06d9 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -5303,7 +5303,7 @@ A type-safe version of :ref:`ceil`, returning an :ref:`Variant` **clamp** **(** :ref:`Variant` value, :ref:`Variant` min, :ref:`Variant` max **)** -Clamps the ``value``, returning a :ref:`Variant` not less than ``min`` and not more than ``max``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. +Clamps the ``value``, returning a :ref:`Variant` not less than ``min`` and not more than ``max``. Any values that can be compared with the less than and greater than operators will work. :: @@ -5325,7 +5325,7 @@ Clamps the ``value``, returning a :ref:`Variant` not less than `` var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6)) # f is (-4, -5, -6) -\ **Note:** For better type safety, use :ref:`clampf`, :ref:`clampi`, :ref:`Vector2.clamp`, :ref:`Vector2i.clamp`, :ref:`Vector3.clamp`, :ref:`Vector3i.clamp`, :ref:`Vector4.clamp`, or :ref:`Vector4i.clamp`. +\ **Note:** For better type safety, use :ref:`clampf`, :ref:`clampi`, :ref:`Vector2.clamp`, :ref:`Vector2i.clamp`, :ref:`Vector3.clamp`, :ref:`Vector3i.clamp`, :ref:`Vector4.clamp`, :ref:`Vector4i.clamp`, or :ref:`Color.clamp`. .. rst-class:: classref-item-separator @@ -6230,7 +6230,7 @@ The following BBCode tags are supported: ``b``, ``i``, ``u``, ``s``, ``indent``, Color tags only support the following named colors: ``black``, ``red``, ``green``, ``yellow``, ``blue``, ``magenta``, ``pink``, ``purple``, ``cyan``, ``white``, ``orange``, ``gray``. Hexadecimal color codes are not supported. -URL tags only support URLs wrapped by an URL tag, not URLs with a different title. +URL tags only support URLs wrapped by a URL tag, not URLs with a different title. When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, ``code`` is represented with faint text but without any font change. Unsupported tags are left as-is in standard output. diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 3dce76104d7..ea5ab670e96 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -10,7 +10,7 @@ AABB ==== -Axis-Aligned Bounding Box. +A 3D axis-aligned bounding box. .. rst-class:: classref-introduction-group diff --git a/classes/class_acceptdialog.rst b/classes/class_acceptdialog.rst index 0ab313ec234..b7742ded138 100644 --- a/classes/class_acceptdialog.rst +++ b/classes/class_acceptdialog.rst @@ -14,14 +14,14 @@ AcceptDialog **Inherited By:** :ref:`ConfirmationDialog` -Base dialog for user notification. +A base dialog used for user notification. .. rst-class:: classref-introduction-group Description ----------- -This dialog is useful for small notifications to the user about an event. It can only be accepted or closed, with the same result. +The default use of **AcceptDialog** is to allow it to only be accepted or closed, with the same result. However, the :ref:`confirmed` and :ref:`canceled` signals allow to make the two actions different, and the :ref:`add_button` method allows to add custom buttons and actions. .. rst-class:: classref-reftable-group diff --git a/classes/class_aescontext.rst b/classes/class_aescontext.rst index 88c84a081f7..7face9d113d 100644 --- a/classes/class_aescontext.rst +++ b/classes/class_aescontext.rst @@ -12,14 +12,14 @@ AESContext **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Interface to low level AES encryption features. +Provides access to AES encryption/decryption of raw data. .. rst-class:: classref-introduction-group Description ----------- -This class provides access to AES encryption/decryption of raw data. Both AES-ECB and AES-CBC mode are supported. +This class holds the context information required for encryption and decryption operations with AES (Advanced Encryption Standard). Both AES-ECB and AES-CBC modes are supported. .. tabs:: diff --git a/classes/class_animatablebody2d.rst b/classes/class_animatablebody2d.rst index 8d9003e0f66..88eafe26ae4 100644 --- a/classes/class_animatablebody2d.rst +++ b/classes/class_animatablebody2d.rst @@ -12,18 +12,16 @@ AnimatableBody2D **Inherits:** :ref:`StaticBody2D` **<** :ref:`PhysicsBody2D` **<** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Physics body for 2D physics which moves only by script or animation (while affecting other bodies on its path). Useful for moving platforms and doors. +A 2D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path. .. rst-class:: classref-introduction-group Description ----------- -Animatable body for 2D physics. +An animatable 2D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, :ref:`AnimationPlayer`\ s (with :ref:`AnimationPlayer.playback_process_mode` set to ``ANIMATION_PROCESS_PHYSICS``), and :ref:`RemoteTransform2D`. -An animatable body can't be moved by external forces or contacts, but can be moved by script or animation to affect other bodies in its path. It is ideal for implementing moving objects in the environment, such as moving platforms or doors. - -When the body is moved manually, either from code or from an :ref:`AnimationPlayer` (with :ref:`AnimationPlayer.playback_process_mode` set to ``physics``), the physics will automatically compute an estimate of their linear and angular velocity. This makes them very useful for moving platforms or other AnimationPlayer-controlled objects (like a door, a bridge that opens, etc). +When **AnimatableBody2D** is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects. .. rst-class:: classref-reftable-group diff --git a/classes/class_animatablebody3d.rst b/classes/class_animatablebody3d.rst index 563e7eb7a85..38153de4ecb 100644 --- a/classes/class_animatablebody3d.rst +++ b/classes/class_animatablebody3d.rst @@ -12,20 +12,16 @@ AnimatableBody3D **Inherits:** :ref:`StaticBody3D` **<** :ref:`PhysicsBody3D` **<** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Physics body for 3D physics which moves only by script or animation (while affecting other bodies on its path). Useful for moving platforms and doors. +A 3D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path. .. rst-class:: classref-introduction-group Description ----------- -Animatable body for 3D physics. +An animatable 3D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, :ref:`AnimationPlayer`\ s (with :ref:`AnimationPlayer.playback_process_mode` set to ``ANIMATION_PROCESS_PHYSICS``), and :ref:`RemoteTransform3D`. -An animatable body can't be moved by external forces or contacts, but can be moved by script or animation to affect other bodies in its path. It is ideal for implementing moving objects in the environment, such as moving platforms or doors. - -When the body is moved manually, either from code or from an :ref:`AnimationPlayer` (with :ref:`AnimationPlayer.playback_process_mode` set to ``physics``), the physics will automatically compute an estimate of their linear and angular velocity. This makes them very useful for moving platforms or other AnimationPlayer-controlled objects (like a door, a bridge that opens, etc). - -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +When **AnimatableBody3D** is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects. .. rst-class:: classref-introduction-group diff --git a/classes/class_animationnode.rst b/classes/class_animationnode.rst index 8aa6db6d2b5..23f52a02932 100644 --- a/classes/class_animationnode.rst +++ b/classes/class_animationnode.rst @@ -23,7 +23,7 @@ Description Base resource for :ref:`AnimationTree` nodes. In general, it's not used directly, but you can create custom ones with custom blending formulas. -Inherit this when creating nodes mainly for use in :ref:`AnimationNodeBlendTree`, otherwise :ref:`AnimationRootNode` should be used instead. +Inherit this when creating animation nodes mainly for use in :ref:`AnimationNodeBlendTree`, otherwise :ref:`AnimationRootNode` should be used instead. .. rst-class:: classref-introduction-group @@ -111,7 +111,7 @@ Signals **animation_node_removed** **(** :ref:`int` object_id, :ref:`String` name **)** -Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes removes. The nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. +Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes removes. The animation nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. .. rst-class:: classref-item-separator @@ -123,7 +123,7 @@ Emitted by nodes that inherit from this class and that have an internal tree whe **animation_node_renamed** **(** :ref:`int` object_id, :ref:`String` old_name, :ref:`String` new_name **)** -Emitted by nodes that inherit from this class and that have an internal tree when one of their node names changes. The nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. +Emitted by nodes that inherit from this class and that have an internal tree when one of their animation node names changes. The animation nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, and :ref:`AnimationNodeBlendTree`. .. rst-class:: classref-item-separator @@ -135,7 +135,7 @@ Emitted by nodes that inherit from this class and that have an internal tree whe **tree_changed** **(** **)** -Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes changes. The nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, :ref:`AnimationNodeBlendTree` and :ref:`AnimationNodeTransition`. +Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes changes. The animation nodes that emit this signal are :ref:`AnimationNodeBlendSpace1D`, :ref:`AnimationNodeBlendSpace2D`, :ref:`AnimationNodeStateMachine`, :ref:`AnimationNodeBlendTree` and :ref:`AnimationNodeTransition`. .. rst-class:: classref-section-separator @@ -221,7 +221,7 @@ Method Descriptions :ref:`String` **_get_caption** **(** **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to override the text caption for this node. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to override the text caption for this animation node. .. rst-class:: classref-item-separator @@ -233,7 +233,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`AnimationNode` **_get_child_by_name** **(** :ref:`StringName` name **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a child node by its ``name``. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a child animation node by its ``name``. .. rst-class:: classref-item-separator @@ -245,7 +245,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`Dictionary` **_get_child_nodes** **(** **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return all children nodes in order as a ``name: node`` dictionary. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return all children animation nodes in order as a ``name: node`` dictionary. .. rst-class:: classref-item-separator @@ -257,7 +257,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`Variant` **_get_parameter_default_value** **(** :ref:`StringName` parameter **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return the default value of a ``parameter``. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return the default value of a ``parameter``. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. .. rst-class:: classref-item-separator @@ -269,7 +269,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`Array` **_get_parameter_list** **(** **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a list of the properties on this node. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to :ref:`Object.get_property_list`. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a list of the properties on this animation node. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. Format is similar to :ref:`Object.get_property_list`. .. rst-class:: classref-item-separator @@ -281,7 +281,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`bool` **_has_filter** **(** **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the blend tree editor should display filter editing on this node. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the blend tree editor should display filter editing on this animation node. .. rst-class:: classref-item-separator @@ -293,7 +293,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`bool` **_is_parameter_read_only** **(** :ref:`StringName` parameter **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the ``parameter`` is read-only. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the ``parameter`` is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. .. rst-class:: classref-item-separator @@ -305,7 +305,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen :ref:`float` **_process** **(** :ref:`float` time, :ref:`bool` seek, :ref:`bool` is_external_seeking, :ref:`bool` test_only **)** |virtual| |const| -When inheriting from :ref:`AnimationRootNode`, implement this virtual method to run some code when this node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. +When inheriting from :ref:`AnimationRootNode`, implement this virtual method to run some code when this animation node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. Here, call the :ref:`blend_input`, :ref:`blend_node` or :ref:`blend_animation` functions. You can also use :ref:`get_parameter` and :ref:`set_parameter` to modify local memory. @@ -321,7 +321,7 @@ This function should return the time left for the current animation to finish (i :ref:`bool` **add_input** **(** :ref:`String` name **)** -Adds an input to the node. This is only useful for nodes created for use in an :ref:`AnimationNodeBlendTree`. If the addition fails, returns ``false``. +Adds an input to the animation node. This is only useful for animation nodes created for use in an :ref:`AnimationNodeBlendTree`. If the addition fails, returns ``false``. .. rst-class:: classref-item-separator @@ -347,7 +347,7 @@ A ``looped_flag`` is used by internal processing immediately after the loop. See :ref:`float` **blend_input** **(** :ref:`int` input_index, :ref:`float` time, :ref:`bool` seek, :ref:`bool` is_external_seeking, :ref:`float` blend, :ref:`FilterAction` filter=0, :ref:`bool` sync=true, :ref:`bool` test_only=false **)** -Blend an input. This is only useful for nodes created for an :ref:`AnimationNodeBlendTree`. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. A filter mode may be optionally passed (see :ref:`FilterAction` for options). +Blend an input. This is only useful for animation nodes created for an :ref:`AnimationNodeBlendTree`. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute. A filter mode may be optionally passed (see :ref:`FilterAction` for options). .. rst-class:: classref-item-separator @@ -359,7 +359,7 @@ Blend an input. This is only useful for nodes created for an :ref:`AnimationNode :ref:`float` **blend_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`float` time, :ref:`bool` seek, :ref:`bool` is_external_seeking, :ref:`float` blend, :ref:`FilterAction` filter=0, :ref:`bool` sync=true, :ref:`bool` test_only=false **)** -Blend another animation node (in case this node contains children animation nodes). This function is only useful if you inherit from :ref:`AnimationRootNode` instead, else editors will not display your node for addition. +Blend another animation node (in case this animation node contains children animation nodes). This function is only useful if you inherit from :ref:`AnimationRootNode` instead, else editors will not display your animation node for addition. .. rst-class:: classref-item-separator @@ -383,7 +383,7 @@ Returns the input index which corresponds to ``name``. If not found, returns ``- :ref:`int` **get_input_count** **(** **)** |const| -Amount of inputs in this node, only useful for nodes that go into :ref:`AnimationNodeBlendTree`. +Amount of inputs in this animation node, only useful for animation nodes that go into :ref:`AnimationNodeBlendTree`. .. rst-class:: classref-item-separator @@ -407,7 +407,7 @@ Gets the name of an input by index. :ref:`Variant` **get_parameter** **(** :ref:`StringName` name **)** |const| -Gets the value of a parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. +Gets the value of a parameter. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. .. rst-class:: classref-item-separator diff --git a/classes/class_animationnodeadd2.rst b/classes/class_animationnodeadd2.rst index a5d84302898..e365005da7e 100644 --- a/classes/class_animationnodeadd2.rst +++ b/classes/class_animationnodeadd2.rst @@ -19,7 +19,11 @@ Blends two animations additively inside of an :ref:`AnimationNodeBlendTree`. Blends two animations additively based on an amount value in the ``[0.0, 1.0]`` range. +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations additively based on the amount value. + +If the amount is greater than ``1.0``, the animation connected to "in" port is blended with the amplified animation connected to "add" port. + +If the amount is less than ``0.0``, the animation connected to "in" port is blended with the inverted animation connected to "add" port. .. rst-class:: classref-introduction-group diff --git a/classes/class_animationnodeadd3.rst b/classes/class_animationnodeadd3.rst index 9f7231ac6af..78109d78fc4 100644 --- a/classes/class_animationnodeadd3.rst +++ b/classes/class_animationnodeadd3.rst @@ -19,15 +19,17 @@ Blends two of three animations additively inside of an :ref:`AnimationNodeBlendT Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations together additively out of three based on a value in the ``[-1.0, 1.0]`` range. +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations out of three additively out of three based on the amounmt value. -This node has three inputs: +This animation node has three inputs: - The base animation to add to -- A -add animation to blend with when the blend amount is in the ``[-1.0, 0.0]`` range. +- A "-add" animation to blend with when the blend amount is negative -- A +add animation to blend with when the blend amount is in the ``[0.0, 1.0]`` range +- A "+add" animation to blend with when the blend amount is positive + +If the absolute value of the amount is greater than ``1.0``, the animation connected to "in" port is blended with the amplified animation connected to "-add"/"+add" port. .. rst-class:: classref-introduction-group diff --git a/classes/class_animationnodeblend2.rst b/classes/class_animationnodeblend2.rst index 211a716f3ab..abceca448ac 100644 --- a/classes/class_animationnodeblend2.rst +++ b/classes/class_animationnodeblend2.rst @@ -19,7 +19,9 @@ Blends two animations linearly inside of an :ref:`AnimationNodeBlendTree`. Blends two animations linearly based on an amount value in the ``[0.0, 1.0]`` range. +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations linearly based on the amount value. + +In general, the blend value should be in the ``[0.0, 1.0]`` range. Values outside of this range can blend amplified or inverted animations, however, :ref:`AnimationNodeAdd2` works better for this purpose. .. rst-class:: classref-introduction-group diff --git a/classes/class_animationnodeblend3.rst b/classes/class_animationnodeblend3.rst index 73b5678af8f..743ee5a56bf 100644 --- a/classes/class_animationnodeblend3.rst +++ b/classes/class_animationnodeblend3.rst @@ -19,15 +19,17 @@ Blends two of three animations linearly inside of an :ref:`AnimationNodeBlendTre Description ----------- -A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations together linearly out of three based on a value in the ``[-1.0, 1.0]`` range. +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations out of three linearly out of three based on the amounmt value. -This node has three inputs: +This animation node has three inputs: -- The base animation +- The base animation to blend with -- A -blend animation to blend with when the blend amount is in the ``[-1.0, 0.0]`` range. +- A "-blend" animation to blend with when the blend amount is negative value -- A +blend animation to blend with when the blend amount is in the ``[0.0, 1.0]`` range +- A "+blend" animation to blend with when the blend amount is positive value + +In general, the blend value should be in the ``[-1.0, 1.0]`` range. Values outside of this range can blend amplified animations, however, :ref:`AnimationNodeAdd3` works better for this purpose. .. rst-class:: classref-introduction-group diff --git a/classes/class_animationnodeblendspace1d.rst b/classes/class_animationnodeblendspace1d.rst index abb31233fd4..0d9f8384315 100644 --- a/classes/class_animationnodeblendspace1d.rst +++ b/classes/class_animationnodeblendspace1d.rst @@ -107,7 +107,7 @@ The interpolation between animations is linear. :ref:`BlendMode` **BLEND_MODE_DISCRETE** = ``1`` -The blend space plays the animation of the node the blending position is closest to. Useful for frame-by-frame 2D animations. +The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations. .. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE_CARRY: diff --git a/classes/class_animationnodeblendspace2d.rst b/classes/class_animationnodeblendspace2d.rst index c36929ea833..7638c947edd 100644 --- a/classes/class_animationnodeblendspace2d.rst +++ b/classes/class_animationnodeblendspace2d.rst @@ -138,7 +138,7 @@ The interpolation between animations is linear. :ref:`BlendMode` **BLEND_MODE_DISCRETE** = ``1`` -The blend space plays the animation of the node the blending position is closest to. Useful for frame-by-frame 2D animations. +The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations. .. _class_AnimationNodeBlendSpace2D_constant_BLEND_MODE_DISCRETE_CARRY: diff --git a/classes/class_animationnodeblendtree.rst b/classes/class_animationnodeblendtree.rst index 90da4bcb69b..48b1d6cec75 100644 --- a/classes/class_animationnodeblendtree.rst +++ b/classes/class_animationnodeblendtree.rst @@ -12,14 +12,14 @@ AnimationNodeBlendTree **Inherits:** :ref:`AnimationRootNode` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A sub-tree of blend type :ref:`AnimationNode`\ s used for complex animations. Used by :ref:`AnimationTree`. +A sub-tree of many type :ref:`AnimationNode`\ s used for complex animations. Used by :ref:`AnimationTree`. .. rst-class:: classref-introduction-group Description ----------- -This node may contain a sub-tree of any other blend type nodes, such as :ref:`AnimationNodeTransition`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, etc. This is one of the most commonly used animation node roots. +This animation node may contain a sub-tree of any other type animation nodes, such as :ref:`AnimationNodeTransition`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, etc. This is one of the most commonly used animation node roots. An :ref:`AnimationNodeOutput` node named ``output`` is created by default. @@ -164,7 +164,7 @@ Property Descriptions - void **set_graph_offset** **(** :ref:`Vector2` value **)** - :ref:`Vector2` **get_graph_offset** **(** **)** -The global offset of all sub-nodes. +The global offset of all sub animation nodes. .. rst-class:: classref-section-separator @@ -181,7 +181,7 @@ Method Descriptions void **add_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`Vector2` position=Vector2(0, 0) **)** -Adds an :ref:`AnimationNode` at the given ``position``. The ``name`` is used to identify the created sub-node later. +Adds an :ref:`AnimationNode` at the given ``position``. The ``name`` is used to identify the created sub animation node later. .. rst-class:: classref-item-separator @@ -205,7 +205,7 @@ Connects the output of an :ref:`AnimationNode` as input for void **disconnect_node** **(** :ref:`StringName` input_node, :ref:`int` input_index **)** -Disconnects the node connected to the specified input. +Disconnects the animation node connected to the specified input. .. rst-class:: classref-item-separator @@ -217,7 +217,7 @@ Disconnects the node connected to the specified input. :ref:`AnimationNode` **get_node** **(** :ref:`StringName` name **)** |const| -Returns the sub-node with the specified ``name``. +Returns the sub animation node with the specified ``name``. .. rst-class:: classref-item-separator @@ -229,7 +229,7 @@ Returns the sub-node with the specified ``name``. :ref:`Vector2` **get_node_position** **(** :ref:`StringName` name **)** |const| -Returns the position of the sub-node with the specified ``name``. +Returns the position of the sub animation node with the specified ``name``. .. rst-class:: classref-item-separator @@ -241,7 +241,7 @@ Returns the position of the sub-node with the specified ``name``. :ref:`bool` **has_node** **(** :ref:`StringName` name **)** |const| -Returns ``true`` if a sub-node with specified ``name`` exists. +Returns ``true`` if a sub animation node with specified ``name`` exists. .. rst-class:: classref-item-separator @@ -253,7 +253,7 @@ Returns ``true`` if a sub-node with specified ``name`` exists. void **remove_node** **(** :ref:`StringName` name **)** -Removes a sub-node. +Removes a sub animation node. .. rst-class:: classref-item-separator @@ -265,7 +265,7 @@ Removes a sub-node. void **rename_node** **(** :ref:`StringName` name, :ref:`StringName` new_name **)** -Changes the name of a sub-node. +Changes the name of a sub animation node. .. rst-class:: classref-item-separator @@ -277,7 +277,7 @@ Changes the name of a sub-node. void **set_node_position** **(** :ref:`StringName` name, :ref:`Vector2` position **)** -Modifies the position of a sub-node. +Modifies the position of a sub animation node. .. |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_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index 0dd9e199cc1..e28b64332da 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -19,7 +19,7 @@ Plays an animation once in an :ref:`AnimationNodeBlendTree`. This node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. +A resource to add to an :ref:`AnimationNodeBlendTree`. This animation node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. After setting the request and changing the animation playback, the one-shot node automatically clears the request on the next process frame by setting its ``request`` value to :ref:`ONE_SHOT_REQUEST_NONE`. @@ -56,13 +56,13 @@ After setting the request and changing the animation playback, the one-shot node .. code-tab:: csharp // Play child animation connected to "shot" port. - animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE); + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Fire); // Abort child animation connected to "shot" port. - animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT); + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Abort); // Abort child animation with fading out connected to "shot" port. - animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT); + animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.FadeOut); // Get current state (read-only). animationTree.Get("parameters/OneShot/active"); diff --git a/classes/class_animationnodestatemachine.rst b/classes/class_animationnodestatemachine.rst index 0161f01da9b..520a4021f01 100644 --- a/classes/class_animationnodestatemachine.rst +++ b/classes/class_animationnodestatemachine.rst @@ -19,7 +19,7 @@ A state machine with multiple :ref:`AnimationRootNode`\ Description ----------- -Contains multiple :ref:`AnimationRootNode`\ s representing animation states, connected in a graph. Node transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. +Contains multiple :ref:`AnimationRootNode`\ s representing animation states, connected in a graph. State transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. \ **Example:**\ @@ -221,7 +221,7 @@ Method Descriptions void **add_node** **(** :ref:`StringName` name, :ref:`AnimationNode` node, :ref:`Vector2` position=Vector2(0, 0) **)** -Adds a new node to the graph. The ``position`` is used for display in the editor. +Adds a new animation node to the graph. The ``position`` is used for display in the editor. .. rst-class:: classref-item-separator @@ -233,7 +233,7 @@ Adds a new node to the graph. The ``position`` is used for display in the editor void **add_transition** **(** :ref:`StringName` from, :ref:`StringName` to, :ref:`AnimationNodeStateMachineTransition` transition **)** -Adds a transition between the given nodes. +Adds a transition between the given animation nodes. .. rst-class:: classref-item-separator @@ -281,7 +281,7 @@ Returns the given animation node's name. :ref:`Vector2` **get_node_position** **(** :ref:`StringName` name **)** |const| -Returns the given node's coordinates. Used for display in the editor. +Returns the given animation node's coordinates. Used for display in the editor. .. rst-class:: classref-item-separator @@ -341,7 +341,7 @@ Returns the given transition's end node. :ref:`bool` **has_node** **(** :ref:`StringName` name **)** |const| -Returns ``true`` if the graph contains the given node. +Returns ``true`` if the graph contains the given animation node. .. rst-class:: classref-item-separator @@ -353,7 +353,7 @@ Returns ``true`` if the graph contains the given node. :ref:`bool` **has_transition** **(** :ref:`StringName` from, :ref:`StringName` to **)** |const| -Returns ``true`` if there is a transition between the given nodes. +Returns ``true`` if there is a transition between the given animation nodes. .. rst-class:: classref-item-separator @@ -365,7 +365,7 @@ Returns ``true`` if there is a transition between the given nodes. void **remove_node** **(** :ref:`StringName` name **)** -Deletes the given node from the graph. +Deletes the given animation node from the graph. .. rst-class:: classref-item-separator @@ -377,7 +377,7 @@ Deletes the given node from the graph. void **remove_transition** **(** :ref:`StringName` from, :ref:`StringName` to **)** -Deletes the transition between the two specified nodes. +Deletes the transition between the two specified animation nodes. .. rst-class:: classref-item-separator @@ -401,7 +401,7 @@ Deletes the given transition by index. void **rename_node** **(** :ref:`StringName` name, :ref:`StringName` new_name **)** -Renames the given node. +Renames the given animation node. .. rst-class:: classref-item-separator @@ -439,7 +439,7 @@ Sets the draw offset of the graph. Used for display in the editor. void **set_node_position** **(** :ref:`StringName` name, :ref:`Vector2` position **)** -Sets the node's coordinates. Used for display in the editor. +Sets the animation node's coordinates. Used for display in the editor. .. |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_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index 2f5bc71ad84..412ac528b5c 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -33,7 +33,7 @@ Allows control of :ref:`AnimationTree` state machines creat .. code-tab:: csharp - var stateMachine = GetNode("AnimationTree").Get("parameters/playback") as AnimationNodeStateMachinePlayback; + var stateMachine = GetNode("AnimationTree").Get("parameters/playback").As(); stateMachine.Travel("some_state"); diff --git a/classes/class_animationnodesub2.rst b/classes/class_animationnodesub2.rst new file mode 100644 index 00000000000..7fdcd1b35c8 --- /dev/null +++ b/classes/class_animationnodesub2.rst @@ -0,0 +1,42 @@ +:github_url: hide + +.. DO NOT EDIT THIS FILE!!! +.. Generated automatically from Godot engine sources. +.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. +.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeSub2.xml. + +.. _class_AnimationNodeSub2: + +AnimationNodeSub2 +================= + +**Inherits:** :ref:`AnimationNodeSync` **<** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Blends two animations subtractively inside of an :ref:`AnimationNodeBlendTree`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A resource to add to an :ref:`AnimationNodeBlendTree`. Blends two animations subtractively based on the amount value. + +This animation node is usually used for pre-calculation to cancel out any extra poses from the animation for the "add" animation source in :ref:`AnimationNodeAdd2` or :ref:`AnimationNodeAdd3`. + +In general, the blend value should be in the ``[0.0, 1.0]`` range, but values outside of this range can be used for amplified or inverted animations. + +\ **Note:** This calculation is different from using a negative value in :ref:`AnimationNodeAdd2`, since the transformation matrices do not satisfy the commutative law. **AnimationNodeSub2** multiplies the transformation matrix of the inverted animation from the left side, while negative :ref:`AnimationNodeAdd2` multiplies it from the right side. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`AnimationTree <../tutorials/animation/animation_tree>` + +.. |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.)` +.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` +.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` +.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` +.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` diff --git a/classes/class_animationnodesync.rst b/classes/class_animationnodesync.rst index 45f96b81239..b6afa72d80d 100644 --- a/classes/class_animationnodesync.rst +++ b/classes/class_animationnodesync.rst @@ -12,7 +12,7 @@ AnimationNodeSync **Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, :ref:`AnimationNodeTransition` +**Inherited By:** :ref:`AnimationNodeAdd2`, :ref:`AnimationNodeAdd3`, :ref:`AnimationNodeBlend2`, :ref:`AnimationNodeBlend3`, :ref:`AnimationNodeOneShot`, :ref:`AnimationNodeSub2`, :ref:`AnimationNodeTransition` Base class for :ref:`AnimationNode`\ s with more than two input ports that must be synchronized. diff --git a/classes/class_animationnodetimeseek.rst b/classes/class_animationnodetimeseek.rst index e5b16b3b7a9..4a4de14776f 100644 --- a/classes/class_animationnodetimeseek.rst +++ b/classes/class_animationnodetimeseek.rst @@ -19,7 +19,7 @@ A time-seeking animation node used in :ref:`AnimationTree`. Description ----------- -This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an :ref:`Animation` from the start or a certain playback position inside the :ref:`AnimationNodeBlendTree`. +This animation node can be used to cause a seek command to happen to any sub-children of the animation graph. Use to play an :ref:`Animation` from the start or a certain playback position inside the :ref:`AnimationNodeBlendTree`. After setting the time and changing the animation playback, the time seek node automatically goes into sleep mode on the next process frame by setting its ``seek_request`` value to ``-1.0``. diff --git a/classes/class_animationnodetransition.rst b/classes/class_animationnodetransition.rst index ba47bd5aed3..3bcea87e908 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -41,7 +41,7 @@ After setting the request and changing the animation playback, the transition no animation_tree["parameters/Transition/current_state"] # Get current state index (read-only). - animation_tree.get("parameters/Transition/current_index")) + animation_tree.get("parameters/Transition/current_index") # Alternative syntax (same result as above). animation_tree["parameters/Transition/current_index"] @@ -142,7 +142,7 @@ If ``true``, allows transition to the self state. When the reset option is enabl - void **set_input_count** **(** :ref:`int` value **)** - :ref:`int` **get_input_count** **(** **)** -The number of enabled input ports for this node. +The number of enabled input ports for this animation node. .. rst-class:: classref-item-separator diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index 6052e4bb834..57ac31c3745 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -676,6 +676,8 @@ Returns the :ref:`Animation` with the key ``name``. If the anim Returns the first :ref:`AnimationLibrary` with key ``name`` or ``null`` if not found. +To get the **AnimationPlayer**'s global animation library, use ``get_animation_library("")``. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_animationrootnode.rst b/classes/class_animationrootnode.rst index f20b3753b40..52a9089c52d 100644 --- a/classes/class_animationrootnode.rst +++ b/classes/class_animationrootnode.rst @@ -23,6 +23,8 @@ Description **AnimationRootNode** is a base class for :ref:`AnimationNode`\ s that hold a complete animation. A complete animation refers to the output of an :ref:`AnimationNodeOutput` in an :ref:`AnimationNodeBlendTree` or the output of another **AnimationRootNode**. Used for :ref:`AnimationTree.tree_root` or in other **AnimationRootNode**\ s. +Examples of built-in root nodes include :ref:`AnimationNodeBlendTree` (allows blending nodes between each other using various modes), :ref:`AnimationNodeStateMachine` (allows to configure blending and transitions between nodes using a state machine pattern), :ref:`AnimationNodeBlendSpace2D` (allows linear blending between **three** :ref:`AnimationNode`\ s), :ref:`AnimationNodeBlendSpace1D` (allows linear blending only between **two** :ref:`AnimationNode`\ s). + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index 81fd8f82f58..9cef9783d95 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -12,18 +12,16 @@ Area2D **Inherits:** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -2D area for detection, as well as physics and audio influence. +A region of 2D space that detects other :ref:`CollisionObject2D`\ s entering or exiting it. .. rst-class:: classref-introduction-group Description ----------- -2D area that detects :ref:`CollisionObject2D` nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping) and route audio to custom audio buses. +**Area2D** is a region of 2D space defined by one or multiple :ref:`CollisionShape2D` or :ref:`CollisionPolygon2D` child nodes. It detects when other :ref:`CollisionObject2D`\ s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). -To give the area its shape, add a :ref:`CollisionShape2D` or a :ref:`CollisionPolygon2D` node as a *direct* child (or add multiple such nodes as direct children) of the area. - -\ **Warning:** See :ref:`ConcavePolygonShape2D` for a warning about possibly unexpected behavior when using that shape for an area. +This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. .. rst-class:: classref-introduction-group diff --git a/classes/class_area3d.rst b/classes/class_area3d.rst index 01b702fe1f1..05a46ecf674 100644 --- a/classes/class_area3d.rst +++ b/classes/class_area3d.rst @@ -12,26 +12,26 @@ Area3D **Inherits:** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -3D area for detection, as well as physics and audio influence. +A region of 3D space that detects other :ref:`CollisionObject3D`\ s entering or exiting it. .. rst-class:: classref-introduction-group Description ----------- -3D area that detects :ref:`CollisionObject3D` nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping) and route audio to custom audio buses. +**Area3D** is a region of 3D space defined by one or multiple :ref:`CollisionShape3D` or :ref:`CollisionPolygon3D` child nodes. It detects when other :ref:`CollisionObject3D`\ s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). -To give the area its shape, add a :ref:`CollisionShape3D` or a :ref:`CollisionPolygon3D` node as a *direct* child (or add multiple such nodes as direct children) of the area. +This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. -\ **Warning:** See :ref:`ConcavePolygonShape3D` (also called "trimesh") for a warning about possibly unexpected behavior when using that shape for an area. - -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +\ **Warning:** Using a :ref:`ConcavePolygonShape3D` inside a :ref:`CollisionShape3D` child of this node (created e.g. by using the *Create Trimesh Collision Sibling* option in the *Mesh* menu that appears when selecting a :ref:`MeshInstance3D` node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple :ref:`ConvexPolygonShape3D`\ s or primitive shapes like :ref:`BoxShape3D`, or in some cases it may be replaceable by a :ref:`CollisionPolygon3D`. .. rst-class:: classref-introduction-group Tutorials --------- +- :doc:`Using Area2D <../tutorials/physics/using_area_2d>` + - `3D Platformer Demo `__ - `GUI in 3D Demo `__ diff --git a/classes/class_array.rst b/classes/class_array.rst index 0d33e1730c1..9c16314554a 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -10,14 +10,14 @@ Array ===== -A generic array datatype. +A built-in data structure that holds a sequence of elements. .. rst-class:: classref-introduction-group Description ----------- -A generic array that can contain several elements of any type, accessible by a numerical index starting at 0. Negative indices can be used to count from the back, like in Python (-1 is the last element, -2 is the second to last, etc.). +An array data structure that can contain a sequence of elements of any type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.). \ **Example:**\ @@ -64,8 +64,6 @@ Arrays can be concatenated using the ``+`` operator: -\ **Note:** Concatenating with the ``+=`` operator will create a new array, which has a cost. If you want to append another array to an existing array, :ref:`append_array` is more efficient. - \ **Note:** Arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate`. \ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. diff --git a/classes/class_arrayoccluder3d.rst b/classes/class_arrayoccluder3d.rst index 1d8f63c1a32..96707157921 100644 --- a/classes/class_arrayoccluder3d.rst +++ b/classes/class_arrayoccluder3d.rst @@ -69,9 +69,9 @@ Property Descriptions - void **set_indices** **(** :ref:`PackedInt32Array` value **)** - :ref:`PackedInt32Array` **get_indices** **(** **)** -.. container:: contribute +The occluder's index position. Indices determine which points from the :ref:`vertices` array should be drawn, and in which order. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** The occluder is always updated after setting this value. If creating occluders procedurally, consider using :ref:`set_arrays` instead to avoid updating the occluder twice when it's created. .. rst-class:: classref-item-separator @@ -88,9 +88,9 @@ Property Descriptions - void **set_vertices** **(** :ref:`PackedVector3Array` value **)** - :ref:`PackedVector3Array` **get_vertices** **(** **)** -.. container:: contribute +The occluder's vertex positions in local 3D coordinates. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **Note:** The occluder is always updated after setting this value. If creating occluders procedurally, consider using :ref:`set_arrays` instead to avoid updating the occluder twice when it's created. .. rst-class:: classref-section-separator @@ -107,9 +107,7 @@ Method Descriptions void **set_arrays** **(** :ref:`PackedVector3Array` vertices, :ref:`PackedInt32Array` indices **)** -.. container:: contribute - - There is currently no description for this method. Please help us by :ref:`contributing one `! +Sets :ref:`indices` and :ref:`vertices`, while updating the final occluder only once after both values are set. .. |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_aspectratiocontainer.rst b/classes/class_aspectratiocontainer.rst index ea65e31d234..5600b7ffe43 100644 --- a/classes/class_aspectratiocontainer.rst +++ b/classes/class_aspectratiocontainer.rst @@ -12,21 +12,21 @@ AspectRatioContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Container that preserves its child controls' aspect ratio. +A container that preserves the proportions of its child controls. .. rst-class:: classref-introduction-group Description ----------- -Arranges child controls in a way to preserve their aspect ratio automatically whenever the container is resized. Solves the problem where the container size is dynamic and the contents' size needs to adjust accordingly without losing proportions. +A container type that arranges its child controls in a way that preserves their proportions automatically when the container is resized. Useful when a container has a dynamic size and the child nodes must adjust their sizes accordingly without losing their aspect ratios. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_astar2d.rst b/classes/class_astar2d.rst index d034edeebec..5a056c9259c 100644 --- a/classes/class_astar2d.rst +++ b/classes/class_astar2d.rst @@ -12,14 +12,16 @@ AStar2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -AStar class representation that uses 2D vectors as edges. +An implementation of A\* for finding the shortest path between two vertices on a connected graph in 2D space. .. rst-class:: classref-introduction-group Description ----------- -This is a wrapper for the :ref:`AStar3D` class which uses 2D vectors instead of 3D vectors. +An implementation of the A\* algorithm, used to find the shortest path between two vertices on a connected graph in 2D space. + +See :ref:`AStar3D` for a more thorough explanation on how to use this class. **AStar2D** is a wrapper for :ref:`AStar3D` that enforces 2D coordinates. .. rst-class:: classref-reftable-group @@ -98,7 +100,7 @@ Method Descriptions Called when computing the cost between two connected points. -Note that this function is hidden in the default ``AStar2D`` class. +Note that this function is hidden in the default **AStar2D** class. .. rst-class:: classref-item-separator @@ -112,7 +114,7 @@ Note that this function is hidden in the default ``AStar2D`` class. Called when estimating the cost between a point and the path's ending point. -Note that this function is hidden in the default ``AStar2D`` class. +Note that this function is hidden in the default **AStar2D** class. .. rst-class:: classref-item-separator diff --git a/classes/class_astar3d.rst b/classes/class_astar3d.rst index eeb2a5cc4f1..2d21ffa47e3 100644 --- a/classes/class_astar3d.rst +++ b/classes/class_astar3d.rst @@ -12,16 +12,16 @@ AStar3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -An implementation of A\* to find the shortest paths among connected points in space. +An implementation of A\* for finding the shortest path between two vertices on a connected graph in 3D space. .. rst-class:: classref-introduction-group Description ----------- -A\* (A star) is a computer algorithm that is widely used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Godot's A\* implementation uses points in three-dimensional space and Euclidean distances by default. +A\* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Godot's A\* implementation uses points in 3D space and Euclidean distances by default. -You must add points manually with :ref:`add_point` and create segments manually with :ref:`connect_points`. Then you can test if there is a path between two points with the :ref:`are_points_connected` function, get a path containing indices by :ref:`get_id_path`, or one containing actual coordinates with :ref:`get_point_path`. +You must add points manually with :ref:`add_point` and create segments manually with :ref:`connect_points`. Once done, you can test if there is a path between two points with the :ref:`are_points_connected` function, get a path containing indices by :ref:`get_id_path`, or one containing actual coordinates with :ref:`get_point_path`. It is also possible to use non-Euclidean distances. To do so, create a class that extends ``AStar3D`` and override methods :ref:`_compute_cost` and :ref:`_estimate_cost`. Both take two indices and return a length, as is shown in the following example. diff --git a/classes/class_astargrid2d.rst b/classes/class_astargrid2d.rst index 5315e3c38ba..571856c3726 100644 --- a/classes/class_astargrid2d.rst +++ b/classes/class_astargrid2d.rst @@ -12,16 +12,16 @@ AStarGrid2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A\* (or "A-Star") pathfinding tailored to find the shortest paths on 2D grids. +An implementation of A\* for finding the shortest path between two points on a partial 2D grid. .. rst-class:: classref-introduction-group Description ----------- -Compared to :ref:`AStar2D` you don't need to manually create points or connect them together. It also supports multiple type of heuristics and modes for diagonal movement. This class also provides a jumping mode which is faster to calculate than without it in the :ref:`AStar2D` class. +**AStarGrid2D** is a variant of :ref:`AStar2D` that is specialized for partial 2D grids. It is simpler to use because it doesn't require you to manually create points and connect them together. This class also supports multiple types of heuristics, modes for diagonal movement, and a jumping mode to speed up calculations. -In contrast to :ref:`AStar2D`, you only need set the :ref:`region` of the grid, optionally set the :ref:`cell_size` and then call the :ref:`update` method: +To use **AStarGrid2D**, you only need to set the :ref:`region` of the grid, optionally set the :ref:`cell_size`, and then call the :ref:`update` method: .. tabs:: @@ -46,6 +46,8 @@ In contrast to :ref:`AStar2D`, you only need set the :ref:`region +To remove a point from the pathfinding grid, it must be set as "solid" with :ref:`set_point_solid`. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_audiostreamplaybackpolyphonic.rst b/classes/class_audiostreamplaybackpolyphonic.rst index 4545835bc79..f343acd3133 100644 --- a/classes/class_audiostreamplaybackpolyphonic.rst +++ b/classes/class_audiostreamplaybackpolyphonic.rst @@ -87,7 +87,7 @@ Return true whether the stream associated with an integer ID is still playing. C Play an :ref:`AudioStream` at a given offset, volume and pitch scale. Playback starts immediately. -The return value is an unique integer ID that is associated to this playback stream and which can be used to control it. +The return value is a unique integer ID that is associated to this playback stream and which can be used to control it. This ID becomes invalid when the stream ends (if it does not loop), when the **AudioStreamPlaybackPolyphonic** is stopped, or when :ref:`stop_stream` is called. diff --git a/classes/class_basebutton.rst b/classes/class_basebutton.rst index f88a660008a..ec3b46dbd6f 100644 --- a/classes/class_basebutton.rst +++ b/classes/class_basebutton.rst @@ -14,14 +14,14 @@ BaseButton **Inherited By:** :ref:`Button`, :ref:`LinkButton`, :ref:`TextureButton` -Base class for different kinds of buttons. +Abstract base class for GUI buttons. .. rst-class:: classref-introduction-group Description ----------- -BaseButton is the abstract base class for buttons, so it shouldn't be used directly (it doesn't display anything). Other types of buttons inherit from it. +**BaseButton** is an abstract base class for GUI buttons. It doesn't display anything by itself. .. rst-class:: classref-reftable-group diff --git a/classes/class_basis.rst b/classes/class_basis.rst index 4ffed86dec2..1c48c14f38c 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -10,18 +10,18 @@ Basis ===== -3×3 matrix datatype. +A 3×3 matrix for representing 3D rotation and scale. .. rst-class:: classref-introduction-group Description ----------- -3×3 matrix used for 3D rotation and scale. Almost always used as an orthogonal basis for a :ref:`Transform3D`. +A 3×3 matrix used for representing 3D rotation and scale. Usually used as an orthogonal basis for a :ref:`Transform3D`. Contains 3 vector fields X, Y and Z as its columns, which are typically interpreted as the local basis vectors of a transformation. For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S). -Can also be accessed as array of 3D vectors. These vectors are normally orthogonal to each other, but are not necessarily normalized (due to scaling). +Basis can also be accessed as an array of 3D vectors. These vectors are usually orthogonal to each other, but are not necessarily normalized (due to scaling). For more information, read the "Matrices and transforms" documentation article. @@ -394,7 +394,7 @@ Returns the inverse of the matrix. :ref:`bool` **is_equal_approx** **(** :ref:`Basis` b **)** |const| -Returns ``true`` if this basis and ``b`` are approximately equal, by calling ``is_equal_approx`` on each component. +Returns ``true`` if this basis and ``b`` are approximately equal, by calling :ref:`@GlobalScope.is_equal_approx` on all vector components. .. rst-class:: classref-item-separator @@ -406,7 +406,7 @@ Returns ``true`` if this basis and ``b`` are approximately equal, by calling ``i :ref:`bool` **is_finite** **(** **)** |const| -Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite` on each component. +Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite` on all vector components. .. rst-class:: classref-item-separator diff --git a/classes/class_bool.rst b/classes/class_bool.rst index b892a09c038..3f28dfed530 100644 --- a/classes/class_bool.rst +++ b/classes/class_bool.rst @@ -10,113 +10,59 @@ bool ==== -Boolean built-in type. +A built-in boolean type. .. rst-class:: classref-introduction-group Description ----------- -Boolean is a built-in type. There are two boolean values: ``true`` and ``false``. You can think of it as a switch with on or off (1 or 0) setting. Booleans are used in programming for logic in condition statements, like ``if`` statements. +A **bool** is always one of two values: ``true`` or ``false``, similar to a switch that is either on or off. Booleans are used in programming for logic in condition statements. -Booleans can be directly used in ``if`` statements. The code below demonstrates this on the ``if can_shoot:`` line. You don't need to use ``== true``, you only need ``if can_shoot:``. Similarly, use ``if not can_shoot:`` rather than ``== false``. +Booleans can be directly used in ``if`` and ``elif`` statements. You don't need to add ``== true`` or ``== false``: .. tabs:: .. code-tab:: gdscript - var _can_shoot = true - - func shoot(): - if _can_shoot: - pass # Perform shooting actions here. + if can_shoot: + launch_bullet() .. code-tab:: csharp - private bool _canShoot = true; - - public void Shoot() + if (canShoot) { - if (_canShoot) - { - // Perform shooting actions here. - } + launchBullet(); } -The following code will only create a bullet if both conditions are met: action "shoot" is pressed and if ``can_shoot`` is ``true``. +Many common methods and operations return **bool**\ s, for example, ``shooting_cooldown <= 0.0`` may evaluate to ``true`` or ``false`` depending on the number's value. -\ **Note:** ``Input.is_action_pressed("shoot")`` is also a boolean that is ``true`` when "shoot" is pressed and ``false`` when "shoot" isn't pressed. +\ **bool**\ s are usually used with the logical operators ``and``, ``or``, and ``not`` to create complex conditions: .. tabs:: .. code-tab:: gdscript - var _can_shoot = true + if bullets > 0 and not is_reloading: + launch_bullet() - func shoot(): - if _can_shoot and Input.is_action_pressed("shoot"): - create_bullet() + if bullets == 0 or is_reloading: + play_clack_sound() .. code-tab:: csharp - private bool _canShoot = true; - - public void Shoot() - { - if (_canShoot && Input.IsActionPressed("shoot")) - { - CreateBullet(); - } - } - - - -The following code will set ``can_shoot`` to ``false`` and start a timer. This will prevent player from shooting until the timer runs out. Next ``can_shoot`` will be set to ``true`` again allowing player to shoot once again. - - -.. tabs:: - - .. code-tab:: gdscript - - var _can_shoot = true - @onready var _cool_down = $CoolDownTimer - - func shoot(): - if _can_shoot and Input.is_action_pressed("shoot"): - create_bullet() - _can_shoot = false - _cool_down.start() - - func _on_cool_down_timer_timeout(): - _can_shoot = true - - .. code-tab:: csharp - - private bool _canShoot = true; - private Timer _coolDown; - - public override void _Ready() - { - _coolDown = GetNode("CoolDownTimer"); - } - - public void Shoot() + if (bullets > 0 && !isReloading) { - if (_canShoot && Input.IsActionPressed("shoot")) - { - CreateBullet(); - _canShoot = false; - _coolDown.Start(); - } + launchBullet(); } - public void OnCoolDownTimerTimeout() + if (bullets == 0 || isReloading) { - _canShoot = true; + playClackSound(); } @@ -192,7 +138,7 @@ Constructs a **bool** as a copy of the given **bool**. :ref:`bool` **bool** **(** :ref:`float` from **)** -Cast a :ref:`float` value to a boolean value, this method will return ``false`` if ``0.0`` is passed in, and ``true`` for all other floats. +Cast a :ref:`float` value to a boolean value. This method will return ``false`` if ``0.0`` is passed in, and ``true`` for all other values. .. rst-class:: classref-item-separator @@ -202,7 +148,7 @@ Cast a :ref:`float` value to a boolean value, this method will retu :ref:`bool` **bool** **(** :ref:`int` from **)** -Cast an :ref:`int` value to a boolean value, this method will return ``false`` if ``0`` is passed in, and ``true`` for all other ints. +Cast an :ref:`int` value to a boolean value. This method will return ``false`` if ``0`` is passed in, and ``true`` for all other values. .. rst-class:: classref-section-separator diff --git a/classes/class_boxcontainer.rst b/classes/class_boxcontainer.rst index 50ecac93f14..ee43c27fe98 100644 --- a/classes/class_boxcontainer.rst +++ b/classes/class_boxcontainer.rst @@ -14,21 +14,21 @@ BoxContainer **Inherited By:** :ref:`HBoxContainer`, :ref:`VBoxContainer` -Base class for box containers. +A container that arranges its child controls horizontally or vertically. .. rst-class:: classref-introduction-group Description ----------- -Arranges child :ref:`Control` nodes vertically or horizontally, and rearranges them automatically when their minimum size changes. +A container that arranges its child controls horizontally or vertically, rearranging them automatically when their minimum size changes. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_boxshape3d.rst b/classes/class_boxshape3d.rst index 82884ba67ed..a34883af8b0 100644 --- a/classes/class_boxshape3d.rst +++ b/classes/class_boxshape3d.rst @@ -12,16 +12,16 @@ BoxShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Box shape resource for 3D collisions. +A 3D box shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -3D box shape to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. +A 3D box shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. -\ **Performance:** Being a primitive collision shape, **BoxShape3D** is fast to check collisions against (though not as fast as :ref:`SphereShape3D`). +\ **Performance:** **BoxShape3D** is fast to check collisions against. It is faster than :ref:`CapsuleShape3D` and :ref:`CylinderShape3D`, but slower than :ref:`SphereShape3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_button.rst b/classes/class_button.rst index eab1f85fbfc..a0393dcb2a0 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -14,14 +14,14 @@ Button **Inherited By:** :ref:`CheckBox`, :ref:`CheckButton`, :ref:`ColorPickerButton`, :ref:`MenuButton`, :ref:`OptionButton` -Standard themed Button. +A themed button that can contain text and an icon. .. rst-class:: classref-introduction-group Description ----------- -Button is the standard themed button. It can contain text and an icon, and will display them according to the current :ref:`Theme`. +**Button** is the standard themed button. It can contain text and an icon, and it will display them according to the current :ref:`Theme`. \ **Example of creating a button and assigning an action when pressed by code:**\ @@ -56,11 +56,9 @@ Button is the standard themed button. It can contain text and an icon, and will -Buttons (like all Control nodes) can also be created in the editor, but some situations may require creating them from code. - See also :ref:`BaseButton` which contains common properties and methods associated with this node. -\ **Note:** Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions, as :ref:`TouchScreenButton` supports multitouch. +\ **Note:** Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions. .. rst-class:: classref-introduction-group diff --git a/classes/class_buttongroup.rst b/classes/class_buttongroup.rst index ca28dce45d1..43d2ec067fc 100644 --- a/classes/class_buttongroup.rst +++ b/classes/class_buttongroup.rst @@ -12,16 +12,16 @@ ButtonGroup **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Group of Buttons. +A group of buttons that doesn't allow more than one button to be pressed at a time. .. rst-class:: classref-introduction-group Description ----------- -Group of :ref:`BaseButton`. The members of this group are treated like radio buttons in the sense that only one button can be pressed at the same time. Some types of buttons (such as :ref:`CheckBox`) may have a special appearance for this state. +A group of :ref:`BaseButton`-derived buttons. The buttons in a **ButtonGroup** are treated like radio buttons: No more than one button can be pressed at a time. Some types of buttons (such as :ref:`CheckBox`) may have a special appearance in this state. -Every member of the ButtonGroup should have :ref:`BaseButton.toggle_mode` set to ``true``. +Every member of a **ButtonGroup** should have :ref:`BaseButton.toggle_mode` set to ``true``. .. rst-class:: classref-reftable-group diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 90a9ace5560..e435574a69a 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -10,7 +10,7 @@ Callable ======== -Built-in type representing a method in an object instance or a standalone function. +A built-in type representing a method or a standalone function. .. rst-class:: classref-introduction-group diff --git a/classes/class_camera3d.rst b/classes/class_camera3d.rst index 5b53b19ecd4..eedde2e4f5f 100644 --- a/classes/class_camera3d.rst +++ b/classes/class_camera3d.rst @@ -250,7 +250,13 @@ The :ref:`CameraAttributes` to use for this camera. - void **set_cull_mask** **(** :ref:`int` value **)** - :ref:`int` **get_cull_mask** **(** **)** -The culling mask that describes which 3D render layers are rendered by this camera. +The culling mask that describes which :ref:`VisualInstance3D.layers` are rendered by this camera. By default, all 20 user-visible layers are rendered. + +\ **Note:** Since the :ref:`cull_mask` allows for 32 layers to be stored in total, there are an additional 12 layers that are only used internally by the engine and aren't exposed in the editor. Setting :ref:`cull_mask` using a script allows you to toggle those reserved layers, which can be useful for editor plugins. + +To adjust :ref:`cull_mask` more easily using a script, use :ref:`get_cull_mask_value` and :ref:`set_cull_mask_value`. + +\ **Note:** :ref:`VoxelGI`, SDFGI and :ref:`LightmapGI` will always take all layers into account to determine what contributes to global illumination. If this is an issue, set :ref:`GeometryInstance3D.gi_mode` to :ref:`GeometryInstance3D.GI_MODE_DISABLED` for meshes and :ref:`Light3D.light_bake_mode` to :ref:`Light3D.BAKE_DISABLED` for lights to exclude them from global illumination. .. rst-class:: classref-item-separator @@ -320,7 +326,7 @@ The :ref:`Environment` to use for this camera. - void **set_far** **(** :ref:`float` value **)** - :ref:`float` **get_far** **(** **)** -The distance to the far culling boundary for this camera relative to its local Z axis. +The distance to the far culling boundary for this camera relative to its local Z axis. Higher values allow the camera to see further away, while decreasing :ref:`far` can improve performance if it results in objects being partially or fully culled. .. rst-class:: classref-item-separator @@ -417,7 +423,7 @@ The axis to lock during :ref:`fov`/:ref:`size` value **)** - :ref:`float` **get_near** **(** **)** -The distance to the near culling boundary for this camera relative to its local Z axis. +The distance to the near culling boundary for this camera relative to its local Z axis. Lower values allow the camera to see objects more up close to its origin, at the cost of lower precision across the *entire* range. Values lower than the default can lead to increased Z-fighting. .. rst-class:: classref-item-separator diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index fe7816188e3..ca646c126f3 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -14,24 +14,20 @@ CanvasItem **Inherited By:** :ref:`Control`, :ref:`Node2D` -Base class of anything 2D. +Abstract base class for everything in 2D space. .. rst-class:: classref-introduction-group Description ----------- -Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. **CanvasItem** is extended by :ref:`Control` for anything GUI-related, and by :ref:`Node2D` for anything related to the 2D engine. +Abstract base class for everything in 2D space. Canvas items are laid out in a tree; children inherit and extend their parent's transform. **CanvasItem** is extended by :ref:`Control` for GUI-related nodes, and by :ref:`Node2D` for 2D game objects. -Any **CanvasItem** can draw. For this, :ref:`queue_redraw` is called by the engine, then :ref:`NOTIFICATION_DRAW` will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the **CanvasItem** are provided (see ``draw_*`` functions). However, they can only be used inside :ref:`_draw`, its corresponding :ref:`Object._notification` or methods connected to the :ref:`draw` signal. +Any **CanvasItem** can draw. For this, :ref:`queue_redraw` is called by the engine, then :ref:`NOTIFICATION_DRAW` will be received on idle time to request a redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the **CanvasItem** are provided (see ``draw_*`` functions). However, they can only be used inside :ref:`_draw`, its corresponding :ref:`Object._notification` or methods connected to the :ref:`draw` signal. -Canvas items are drawn in tree order. By default, children are on top of their parents so a root **CanvasItem** will be drawn behind everything. This behavior can be changed on a per-item basis. +Canvas items are drawn in tree order. By default, children are on top of their parents, so a root **CanvasItem** will be drawn behind everything. This behavior can be changed on a per-item basis. -A **CanvasItem** can also be hidden, which will also hide its children. It provides many ways to change parameters such as modulation (for itself and its children) and self modulation (only for itself), as well as its blend mode. - -Ultimately, a transform notification can be requested, which will notify the node that its global position changed in case the parent tree changed. - -\ **Note:** Unless otherwise specified, all methods that have angle parameters must have angles specified as *radians*. To convert degrees to radians, use :ref:`@GlobalScope.deg_to_rad`. +A **CanvasItem** can be hidden, which will also hide its children. By adjusting various other properties of a **CanvasItem**, you can also modulate its color (via :ref:`modulate` or :ref:`self_modulate`), change its Z-index, blend mode, and more. .. rst-class:: classref-introduction-group diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index dacd4239ef2..3c7262ce264 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -14,16 +14,20 @@ CanvasLayer **Inherited By:** :ref:`ParallaxBackground` -Canvas drawing layer. +A node used for independent rendering of objects within a 2D scene. .. rst-class:: classref-introduction-group Description ----------- -Canvas drawing layer. :ref:`CanvasItem` nodes that are direct or indirect children of a **CanvasLayer** will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index 0, so a **CanvasLayer** with index -1 will be drawn below, and one with index 1 will be drawn above. This is very useful for HUDs (in layer 1+ or above), or backgrounds (in layer -1 or below). +:ref:`CanvasItem`-derived nodes that are direct or indirect children of a **CanvasLayer** will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index ``0``, so a **CanvasLayer** with index ``-1`` will be drawn below, and a **CanvasLayer** with index ``1`` will be drawn above. This order will hold regardless of the :ref:`CanvasItem.z_index` of the nodes within each layer. -Embedded :ref:`Window`\ s are placed in layer 1024. CanvasItems in layer 1025 or above appear in front of embedded windows, CanvasItems in layer 1023 or below appear behind embedded windows. +\ **CanvasLayer**\ s can be hidden and they can also optionally follow the viewport. This makes them useful for HUDs like health bar overlays (on layers ``1`` and higher) or backgrounds (on layers ``-1`` and lower). + +\ **Note:** Embedded :ref:`Window`\ s are placed on layer ``1024``. :ref:`CanvasItem`\ s on layers ``1025`` and higher appear in front of embedded windows. + +\ **Note:** Each **CanvasLayer** is drawn on one specific :ref:`Viewport` and cannot be shared between multiple :ref:`Viewport`\ s, see :ref:`custom_viewport`. When using multiple :ref:`Viewport`\ s, for example in a split-screen game, you need create an individual **CanvasLayer** for each :ref:`Viewport` you want it to be drawn on. .. rst-class:: classref-introduction-group diff --git a/classes/class_canvasmodulate.rst b/classes/class_canvasmodulate.rst index 7bfaa1d9aac..dc8deec85f8 100644 --- a/classes/class_canvasmodulate.rst +++ b/classes/class_canvasmodulate.rst @@ -12,14 +12,14 @@ CanvasModulate **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tint the entire canvas. +A node that applies a color tint to a canvas. .. rst-class:: classref-introduction-group Description ----------- -**CanvasModulate** tints the canvas elements using its assigned :ref:`color`. +**CanvasModulate** applies a color tint to all nodes on a canvas. Only one can be used to tint a canvas, but :ref:`CanvasLayer`\ s can be used to render things independently. .. rst-class:: classref-reftable-group diff --git a/classes/class_capsuleshape2d.rst b/classes/class_capsuleshape2d.rst index e6da37198a9..50eecef30c1 100644 --- a/classes/class_capsuleshape2d.rst +++ b/classes/class_capsuleshape2d.rst @@ -12,16 +12,16 @@ CapsuleShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Capsule shape resource for 2D physics. +A 2D capsule shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D capsule shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. In 2D, a capsule is a rectangle shape with half-circles at both ends. +A 2D capsule shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. -\ **Performance:** Being a primitive collision shape, **CapsuleShape2D** is fast to check collisions against (though not as fast as :ref:`CircleShape2D`). +\ **Performance:** **CapsuleShape2D** is fast to check collisions against, but it is slower than :ref:`RectangleShape2D` and :ref:`CircleShape2D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_capsuleshape3d.rst b/classes/class_capsuleshape3d.rst index 18fe5c3d830..e0827225ccf 100644 --- a/classes/class_capsuleshape3d.rst +++ b/classes/class_capsuleshape3d.rst @@ -12,16 +12,16 @@ CapsuleShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Capsule shape resource for 3D collisions. +A 3D capsule shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -3D capsule shape to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. In 3D, a capsule is a cylinder shape with hemispheres at both ends. +A 3D capsule shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. -\ **Performance:** Being a primitive collision shape, **CapsuleShape3D** is fast to check collisions against (though not as fast as :ref:`SphereShape3D`). **CapsuleShape3D** is cheaper to check collisions against compared to :ref:`CylinderShape3D`. +\ **Performance:** **CapsuleShape3D** is fast to check collisions against. It is faster than :ref:`CylinderShape3D`, but slower than :ref:`SphereShape3D` and :ref:`BoxShape3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_centercontainer.rst b/classes/class_centercontainer.rst index a9d885315a0..667f8c4fdc9 100644 --- a/classes/class_centercontainer.rst +++ b/classes/class_centercontainer.rst @@ -12,21 +12,21 @@ CenterContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Keeps children controls centered. +A container that keeps child controls in its center. .. rst-class:: classref-introduction-group Description ----------- -CenterContainer keeps children controls centered. This container keeps all children to their minimum size, in the center. +**CenterContainer** is a container that keeps all of its child controls in its center at their minimum size. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_characterbody2d.rst b/classes/class_characterbody2d.rst index 69cfba3a510..11635f1e1a1 100644 --- a/classes/class_characterbody2d.rst +++ b/classes/class_characterbody2d.rst @@ -12,18 +12,16 @@ CharacterBody2D **Inherits:** :ref:`PhysicsBody2D` **<** :ref:`CollisionObject2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Specialized 2D physics body node for characters moved by script. +A 2D physics body specialized for characters moved by script. .. rst-class:: classref-introduction-group Description ----------- -Character bodies are special types of bodies that are meant to be user-controlled. They are not affected by physics at all; to other types of bodies, such as a rigid body, these are the same as a :ref:`AnimatableBody2D`. However, they have two main uses: +**CharacterBody2D** is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection (:ref:`move_and_slide` method) in addition to the general collision detection provided by :ref:`PhysicsBody2D.move_and_collide`. This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters. -\ **Kinematic characters:** Character bodies have an API for moving objects with walls and slopes detection (:ref:`move_and_slide` method), in addition to collision detection (also done with :ref:`PhysicsBody2D.move_and_collide`). This makes them really useful to implement characters that move in specific ways and collide with the world, but don't require advanced physics. - -\ **Kinematic motion:** Character bodies can also be used for kinematic motion (same functionality as :ref:`AnimatableBody2D`), which allows them to be moved by code and push other bodies on their path. +For game objects that don't require complex movement or collision detection, such as moving platforms, :ref:`AnimatableBody2D` is simpler to configure. .. rst-class:: classref-introduction-group diff --git a/classes/class_characterbody3d.rst b/classes/class_characterbody3d.rst index d1104863695..2ca2a5b6ac0 100644 --- a/classes/class_characterbody3d.rst +++ b/classes/class_characterbody3d.rst @@ -12,20 +12,16 @@ CharacterBody3D **Inherits:** :ref:`PhysicsBody3D` **<** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Specialized 3D physics body node for characters moved by script. +A 3D physics body specialized for characters moved by script. .. rst-class:: classref-introduction-group Description ----------- -Character bodies are special types of bodies that are meant to be user-controlled. They are not affected by physics at all; to other types of bodies, such as a rigid body, these are the same as a :ref:`AnimatableBody3D`. However, they have two main uses: +**CharacterBody3D** is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection (:ref:`move_and_slide` method) in addition to the general collision detection provided by :ref:`PhysicsBody3D.move_and_collide`. This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters. -\ *Kinematic characters:* Character bodies have an API for moving objects with walls and slopes detection (:ref:`move_and_slide` method), in addition to collision detection (also done with :ref:`PhysicsBody3D.move_and_collide`). This makes them really useful to implement characters that move in specific ways and collide with the world, but don't require advanced physics. - -\ *Kinematic motion:* Character bodies can also be used for kinematic motion (same functionality as :ref:`AnimatableBody3D`), which allows them to be moved by code and push other bodies on their path. - -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +For game objects that don't require complex movement or collision detection, such as moving platforms, :ref:`AnimatableBody3D` is simpler to configure. .. rst-class:: classref-introduction-group diff --git a/classes/class_checkbox.rst b/classes/class_checkbox.rst index f37d92cdd39..d6c64713d1b 100644 --- a/classes/class_checkbox.rst +++ b/classes/class_checkbox.rst @@ -12,18 +12,18 @@ CheckBox **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Binary choice user interface widget. See also :ref:`CheckButton`. +A button that represents a binary choice. .. rst-class:: classref-introduction-group Description ----------- -A checkbox allows the user to make a binary choice (choosing only one of two possible options). It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckBox when toggling it has **no** immediate effect on something. For example, it could be used when toggling it will only do something once a confirmation button is pressed. +**CheckBox** allows the user to choose one of only two possible options. It's similar to :ref:`CheckButton` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckBox** when toggling it has **no** immediate effect on something. For example, it could be used when toggling it will only do something once a confirmation button is pressed. See also :ref:`BaseButton` which contains common properties and methods associated with this node. -\ **Note:** CheckBox changes its appearance when it's configured as a radio button. See various ``radio_*`` theme properties. To configure CheckBox to act as a radio button, use :ref:`BaseButton.button_group` and :ref:`ButtonGroup`. +When :ref:`BaseButton.button_group` specifies a :ref:`ButtonGroup`, **CheckBox** changes its appearance to that of a radio button and uses the various ``radio_*`` theme properties. .. rst-class:: classref-reftable-group diff --git a/classes/class_checkbutton.rst b/classes/class_checkbutton.rst index 1c89da3dd96..9feeee9442a 100644 --- a/classes/class_checkbutton.rst +++ b/classes/class_checkbutton.rst @@ -12,14 +12,14 @@ CheckButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Checkable button. See also :ref:`CheckBox`. +A button that represents a binary choice. .. rst-class:: classref-introduction-group Description ----------- -CheckButton is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use CheckButton when toggling it has an **immediate** effect on something. For example, it could be used if toggling it enables/disables a setting without requiring the user to press a confirmation button. +**CheckButton** is a toggle button displayed as a check field. It's similar to :ref:`CheckBox` in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckButton** when toggling it has an **immediate** effect on something. For example, it can be used when pressing it shows or hides advanced settings, without asking the user to confirm this action. See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_circleshape2d.rst b/classes/class_circleshape2d.rst index dc453acbcac..a6e43ce21d3 100644 --- a/classes/class_circleshape2d.rst +++ b/classes/class_circleshape2d.rst @@ -12,16 +12,16 @@ CircleShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Circular shape resource for 2D physics. +A 2D circle shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D circular shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. This shape is useful for modeling balls or small characters and its collision detection with everything else is very fast. +A 2D circle shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. -\ **Performance:** Being a primitive collision shape, **CircleShape2D** is the fastest collision shape to check collisions against, as it only requires a distance check with the shape's origin. +\ **Performance:** **CircleShape2D** is fast to check collisions against. It is faster than :ref:`RectangleShape2D` and :ref:`CapsuleShape2D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_classdb.rst b/classes/class_classdb.rst index 57e0559819c..8483398b7c2 100644 --- a/classes/class_classdb.rst +++ b/classes/class_classdb.rst @@ -12,7 +12,7 @@ ClassDB **Inherits:** :ref:`Object` -Class information repository. +A class information repository. .. rst-class:: classref-introduction-group diff --git a/classes/class_codeedit.rst b/classes/class_codeedit.rst index 2fefce2f522..3965e178e28 100644 --- a/classes/class_codeedit.rst +++ b/classes/class_codeedit.rst @@ -12,16 +12,16 @@ CodeEdit **Inherits:** :ref:`TextEdit` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Multiline text control intended for editing code. +A multiline text editor designed for editing code. .. rst-class:: classref-introduction-group Description ----------- -CodeEdit is a specialized :ref:`TextEdit` designed for editing plain text code files. It contains a bunch of features commonly found in code editors such as line numbers, line folding, code completion, indent management and string / comment management. +CodeEdit is a specialized :ref:`TextEdit` designed for editing plain text code files. It has many features commonly found in code editors such as line numbers, line folding, code completion, indent management, and string/comment management. -\ **Note:** By default **CodeEdit** always use left-to-right text direction to correctly display source code. +\ **Note:** Regardless of locale, **CodeEdit** will by default always use left-to-right text direction to correctly display source code. .. rst-class:: classref-reftable-group diff --git a/classes/class_codehighlighter.rst b/classes/class_codehighlighter.rst index 7e2d3e0387b..022185e42c6 100644 --- a/classes/class_codehighlighter.rst +++ b/classes/class_codehighlighter.rst @@ -12,14 +12,14 @@ CodeHighlighter **Inherits:** :ref:`SyntaxHighlighter` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A syntax highlighter for code. +A syntax highlighter intended for code. .. rst-class:: classref-introduction-group Description ----------- -A syntax highlighter for code. +By adjusting various properties of this resource, you can change the colors of strings, comments, numbers, and other text patterns inside a :ref:`TextEdit` control. .. rst-class:: classref-reftable-group diff --git a/classes/class_collisionobject2d.rst b/classes/class_collisionobject2d.rst index 123f4188713..5bcbf56944d 100644 --- a/classes/class_collisionobject2d.rst +++ b/classes/class_collisionobject2d.rst @@ -14,14 +14,14 @@ CollisionObject2D **Inherited By:** :ref:`Area2D`, :ref:`PhysicsBody2D` -Base node for 2D collision objects. +Abstract base class for 2D physics objects. .. rst-class:: classref-introduction-group Description ----------- -CollisionObject2D is the base class for 2D physics objects. It can hold any number of 2D collision :ref:`Shape2D`\ s. Each shape must be assigned to a *shape owner*. The CollisionObject2D can have any number of shape owners. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. +Abstract base class for 2D physics objects. **CollisionObject2D** can hold any number of :ref:`Shape2D`\ s for collision. Each shape must be assigned to a *shape owner*. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. \ **Note:** Only collisions between objects within the same canvas (:ref:`Viewport` canvas or :ref:`CanvasLayer`) are supported. The behavior of collisions between objects in different canvases is undefined. diff --git a/classes/class_collisionobject3d.rst b/classes/class_collisionobject3d.rst index 9766d82f93b..b31de7da96b 100644 --- a/classes/class_collisionobject3d.rst +++ b/classes/class_collisionobject3d.rst @@ -14,16 +14,16 @@ CollisionObject3D **Inherited By:** :ref:`Area3D`, :ref:`PhysicsBody3D` -Base node for collision objects. +Abstract base class for 3D physics objects. .. rst-class:: classref-introduction-group Description ----------- -CollisionObject3D is the base class for physics objects. It can hold any number of collision :ref:`Shape3D`\ s. Each shape must be assigned to a *shape owner*. The CollisionObject3D can have any number of shape owners. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. +Abstract base class for 3D physics objects. **CollisionObject3D** can hold any number of :ref:`Shape3D`\ s for collision. Each shape must be assigned to a *shape owner*. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +\ **Warning:** With a non-uniform scale, this node will likely not behave as expected. It is advised to keep its scale the same on all axes and adjust its collision shape(s) instead. .. rst-class:: classref-reftable-group diff --git a/classes/class_collisionpolygon2d.rst b/classes/class_collisionpolygon2d.rst index f066c8cf48a..059269aa9a5 100644 --- a/classes/class_collisionpolygon2d.rst +++ b/classes/class_collisionpolygon2d.rst @@ -12,18 +12,16 @@ CollisionPolygon2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Node that represents a 2D collision polygon. +A node that provides a polygon shape to a :ref:`CollisionObject2D` parent. .. rst-class:: classref-introduction-group Description ----------- -Provides a 2D collision polygon to a :ref:`CollisionObject2D` parent. Polygons can be drawn in the editor or specified by a list of vertices. +A node that provides a thickened polygon shape (a prism) to a :ref:`CollisionObject2D` parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an :ref:`Area2D` or turn :ref:`PhysicsBody2D` into a solid object. -Depending on the build mode, this node effectively provides several convex shapes (by convex decomposition of the polygon) or a single concave shape made of the polygon's segments. - -In the editor, a **CollisionPolygon2D** can be generated from a :ref:`Sprite2D`'s outline by selecting a :ref:`Sprite2D` node, going to the **Sprite2D** menu at the top of the 2D editor viewport then choosing **Create CollisionPolygon2D Sibling**. +\ **Warning:** A non-uniformly scaled :ref:`CollisionShape3D` will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead. .. rst-class:: classref-reftable-group diff --git a/classes/class_collisionpolygon3d.rst b/classes/class_collisionpolygon3d.rst index e811559a9c0..79dcc77bfb0 100644 --- a/classes/class_collisionpolygon3d.rst +++ b/classes/class_collisionpolygon3d.rst @@ -12,18 +12,16 @@ CollisionPolygon3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Node that represents a 3D collision polygon, given by the thickening of a 2D polygon in the local XY plane along the local Z axis. +A node that provides a thickened polygon shape (a prism) to a :ref:`CollisionObject3D` parent. .. rst-class:: classref-introduction-group Description ----------- -Provides a 3D collision polygon to a :ref:`CollisionObject3D` parent, by thickening a 2D (convex or concave) polygon in the local XY plane along the local Z axis. The 2D polygon in the local XY plane can be drawn in the editor or specified by a list of vertices. That 2D polygon is thickened evenly in the local Z and -Z directions. +A node that provides a thickened polygon shape (a prism) to a :ref:`CollisionObject3D` parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an :ref:`Area3D` or turn :ref:`PhysicsBody3D` into a solid object. -This node has the same effect as several :ref:`ConvexPolygonShape3D` nodes, created by thickening the 2D convex polygons in the convex decomposition of the given 2D polygon (but without the overhead of multiple nodes). - -\ **Warning:** A non-uniformly scaled CollisionPolygon3D node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change its :ref:`polygon`'s vertices instead. +\ **Warning:** A non-uniformly scaled :ref:`CollisionShape3D` will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead. .. rst-class:: classref-reftable-group diff --git a/classes/class_collisionshape2d.rst b/classes/class_collisionshape2d.rst index 07579d5cfd4..a4f216f3e49 100644 --- a/classes/class_collisionshape2d.rst +++ b/classes/class_collisionshape2d.rst @@ -12,16 +12,14 @@ CollisionShape2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Node that represents collision shape data in 2D space. +A node that provides a :ref:`Shape2D` to a :ref:`CollisionObject2D` parent. .. rst-class:: classref-introduction-group Description ----------- -Editor facility for creating and editing collision shapes in 2D space. Set the :ref:`shape` property to configure the shape. - -You can use this node to represent all sorts of collision shapes, for example, add this to an :ref:`Area2D` to give it a detection shape, or add it to a :ref:`PhysicsBody2D` to create a solid object. +A node that provides a :ref:`Shape2D` to a :ref:`CollisionObject2D` parent and allows to edit it. This can give a detection shape to an :ref:`Area2D` or turn a :ref:`PhysicsBody2D` into a solid object. .. rst-class:: classref-introduction-group diff --git a/classes/class_collisionshape3d.rst b/classes/class_collisionshape3d.rst index 0802b638da7..2ecafb7a1f9 100644 --- a/classes/class_collisionshape3d.rst +++ b/classes/class_collisionshape3d.rst @@ -12,18 +12,16 @@ CollisionShape3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Node that represents collision shape data in 3D space. +A node that provides a :ref:`Shape3D` to a :ref:`CollisionObject3D` parent. .. rst-class:: classref-introduction-group Description ----------- -Editor facility for creating and editing collision shapes in 3D space. Set the :ref:`shape` property to configure the shape. +A node that provides a :ref:`Shape3D` to a :ref:`CollisionObject3D` parent and allows to edit it. This can give a detection shape to an :ref:`Area3D` or turn a :ref:`PhysicsBody3D` into a solid object. -You can use this node to represent all sorts of collision shapes, for example, add this to an :ref:`Area3D` to give it a detection shape, or add it to a :ref:`PhysicsBody3D` to create a solid object. - -\ **Warning:** A non-uniformly scaled CollisionShape3D node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size of its :ref:`shape` resource instead. +\ **Warning:** A non-uniformly scaled **CollisionShape3D** will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its :ref:`shape` resource instead. .. rst-class:: classref-introduction-group diff --git a/classes/class_color.rst b/classes/class_color.rst index 22f6485d4d2..b9264ceb3e7 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -10,18 +10,18 @@ Color ===== -Color built-in type, in RGBA format. +A color represented in RGBA format. .. rst-class:: classref-introduction-group Description ----------- -A color represented in RGBA format by red (:ref:`r`), green (:ref:`g`), blue (:ref:`b`), and alpha (:ref:`a`) components. Each component is a 16-bit floating-point value, usually ranging from 0 to 1. Some properties (such as :ref:`CanvasItem.modulate`) may support values greater than 1, for overbright or High Dynamic Range colors. If you want to supply values in a range of 0 to 255, you should use :ref:`@GDScript.Color8`. +A color represented in RGBA format by a red (:ref:`r`), green (:ref:`g`), blue (:ref:`b`), and alpha (:ref:`a`) component. Each component is a 16-bit floating-point value, usually ranging from ``0.0`` to ``1.0``. Some properties (such as :ref:`CanvasItem.modulate`) may support values greater than ``1.0``, for overbright or HDR (High Dynamic Range) colors. -Colors can also be created by name from a set of standardized colors, through the :ref:`String` constructor, :ref:`from_string`, or by directly fetching the color constants documented here. The standardized color set is based on the `X11 color names `__, with the addition of :ref:`TRANSPARENT`. +Colors can be created in various ways: By the various **Color** constructors, by static methods such as :ref:`from_hsv`, and by using a name from the set of standardized colors based on `X11 color names `__ with the addition of :ref:`TRANSPARENT`. GDScript also provides :ref:`@GDScript.Color8`, which uses integers from ``0`` to ``255`` and doesn't support overbright colors. -\ **Note:** In a boolean context, a Color will evaluate to ``false`` if it's equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. +\ **Note:** In a boolean context, a Color will evaluate to ``false`` if it is equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. \ `Color constants cheatsheet `__ @@ -1791,9 +1791,9 @@ Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclus :ref:`Color` **hex** **(** :ref:`int` hex **)** |static| -Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel, alpha channel first). +Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel). -In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix). +In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRGGBBAA"``). .. tabs:: @@ -1822,9 +1822,9 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima :ref:`Color` **hex64** **(** :ref:`int` hex **)** |static| -Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel, alpha channel first). +Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel). -In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix). +In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRRRGGGGBBBBAAAA"``). .. rst-class:: classref-item-separator diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index 228db859c99..9fccb00575b 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -12,16 +12,16 @@ ColorPicker **Inherits:** :ref:`VBoxContainer` **<** :ref:`BoxContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Color picker control. +A widget that provides an interface for selecting or modifying a color. .. rst-class:: classref-introduction-group Description ----------- -Displays a color picker widget. Useful for selecting a color from an RGB/RGBA colorspace. +A widget that provides an interface for selecting or modifying a color. It can optionally provide functionalities like a color sampler (eyedropper), color modes, and presets. -\ **Note:** This control is the color picker widget itself. You can use a :ref:`ColorPickerButton` instead if you need a button that brings up a **ColorPicker** in a pop-up. +\ **Note:** This control is the color picker widget itself. You can use a :ref:`ColorPickerButton` instead if you need a button that brings up a **ColorPicker** in a popup. .. rst-class:: classref-introduction-group diff --git a/classes/class_colorpickerbutton.rst b/classes/class_colorpickerbutton.rst index 7d706e611b6..86186be2b16 100644 --- a/classes/class_colorpickerbutton.rst +++ b/classes/class_colorpickerbutton.rst @@ -12,14 +12,14 @@ ColorPickerButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Button that pops out a :ref:`ColorPicker`. +A button that brings up a :ref:`ColorPicker` when pressed. .. rst-class:: classref-introduction-group Description ----------- -Encapsulates a :ref:`ColorPicker` making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker` visibility. +Encapsulates a :ref:`ColorPicker`, making it accessible by pressing a button. Pressing the button will toggle the :ref:`ColorPicker`'s visibility. See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_colorrect.rst b/classes/class_colorrect.rst index 532f8c328d5..8453cf5e70b 100644 --- a/classes/class_colorrect.rst +++ b/classes/class_colorrect.rst @@ -12,14 +12,14 @@ ColorRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Colored rectangle. +A control that displays a solid color rectangle. .. rst-class:: classref-introduction-group Description ----------- -Displays a rectangle filled with a solid :ref:`color`. If you need to display the border alone, consider using :ref:`ReferenceRect` instead. +Displays a rectangle filled with a solid :ref:`color`. If you need to display the border alone, consider using a :ref:`Panel` instead. .. rst-class:: classref-introduction-group @@ -60,20 +60,7 @@ Property Descriptions - void **set_color** **(** :ref:`Color` value **)** - :ref:`Color` **get_color** **(** **)** -The fill color. - - -.. tabs:: - - .. code-tab:: gdscript - - $ColorRect.color = Color(1, 0, 0, 1) # Set ColorRect's color to red. - - .. code-tab:: csharp - - GetNode("ColorRect").Color = new Color(1, 0, 0, 1); // Set ColorRect's color to red. - - +The fill color of the rectangle. .. |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_concavepolygonshape2d.rst b/classes/class_concavepolygonshape2d.rst index 4661fe96d1c..43efacf3bce 100644 --- a/classes/class_concavepolygonshape2d.rst +++ b/classes/class_concavepolygonshape2d.rst @@ -12,26 +12,22 @@ ConcavePolygonShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Concave polygon shape resource for 2D physics. +A 2D polyline shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D concave polygon shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. +A 2D polyline shape, intended for use in physics. Used internally in :ref:`CollisionPolygon2D` when it's in ``BUILD_SEGMENTS`` mode. -The shape consists of a collection of line segments, and as such it does not include any "inside" that the segments might be enclosing. If the segments do enclose anything, then the shape is *hollow*, as opposed to a :ref:`ConvexPolygonShape2D` which is solid. See also :ref:`CollisionPolygon2D`. +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 made out of line segments, this shape is the most freely configurable single 2D shape. It can be used to form (hollow) polygons of any nature, convex or concave. +\ **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. -\ **Note:** When used for collision, **ConcavePolygonShape2D** is intended to work with static :ref:`PhysicsBody2D` nodes like :ref:`StaticBody2D` and is not recommended to use with :ref:`RigidBody2D` nodes in a mode other than Static. A :ref:`CollisionPolygon2D` in convex decomposition mode (solids) or several convex objects are advised for that instead. Otherwise, a concave polygon 2D shape is better suited for static bodies. +\ **Warning:** Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. **ConcavePolygonShape2D** is hollow, so it won't detect a collision. -\ **Warning:** The nature of this shape makes it extra prone to being tunneled through by (small) fast physics bodies. For example, consider a (small) rigid body *Ball* traveling toward a static body *Box* at high speed. If the box uses a **ConcavePolygonShape2D** consisting of four segments, then the ball might end up inside the box or tunnel all the way through the box, if it goes fast enough. This is (partly) because the ball can only collide against the individual segments of the hollow box. In interactions with rigid bodies tunneling can be avoided by enabling continuous collision detection on the rigid body. - -\ **Warning:** Using this shape for an :ref:`Area2D` (via a :ref:`CollisionShape2D` node) may give unexpected results: the area will only detect collisions with the segments in the **ConcavePolygonShape2D** (and not with any "inside" of the shape, for example). - -\ **Performance:** Due to its complexity, **ConcavePolygonShape2D** is the slowest collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, using :ref:`ConvexPolygonShape2D` will perform better. For dynamic physics bodies that need concave collision, several :ref:`ConvexPolygonShape2D`\ s can be used to represent its collision by using convex decomposition; see :ref:`ConvexPolygonShape2D`'s documentation for instructions. However, consider using primitive collision shapes such as :ref:`CircleShape2D` or :ref:`RectangleShape2D` first. +\ **Performance:** Due to its complexity, **ConcavePolygonShape2D** is the slowest 2D collision shape to check collisions against. Its use should generally be limited to level geometry. If the polyline is closed, :ref:`CollisionPolygon2D`'s ``BUILD_SOLIDS`` mode can be used, which decomposes the polygon into convex ones; see :ref:`ConvexPolygonShape2D`'s documentation for instructions. .. rst-class:: classref-reftable-group diff --git a/classes/class_concavepolygonshape3d.rst b/classes/class_concavepolygonshape3d.rst index 39496bc2946..c2bcb29b111 100644 --- a/classes/class_concavepolygonshape3d.rst +++ b/classes/class_concavepolygonshape3d.rst @@ -12,26 +12,22 @@ ConcavePolygonShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Concave polygon shape resource (also called "trimesh") for 3D physics. +A 3D trimesh shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -3D concave polygon shape resource (also called "trimesh") to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. +A 3D trimesh shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. -The shape consists of a collection of triangle faces, and as such it does not include any "inside" that the faces might be enclosing. If the faces enclose anything, then the shape is *hollow*, as opposed to a :ref:`ConvexPolygonShape3D` which is solid. See also :ref:`CollisionPolygon3D`. +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 made out of triangle faces, this shape is the most freely configurable single 3D shape. Despite its name, it can be used to form (hollow) polyhedra of any nature, convex or concave. +\ **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. -\ **Note:** When used for collision, **ConcavePolygonShape3D** is intended to work with static :ref:`PhysicsBody3D` nodes like :ref:`StaticBody3D` and will not work with :ref:`CharacterBody3D` or :ref:`RigidBody3D` in a mode other than Static. +\ **Warning:** Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. **ConcavePolygonShape3D** is hollow, so it won't detect a collision. -\ **Warning:** The nature of this shape makes it extra prone to being tunneled through by (small) fast physics bodies. For example, consider a (small) rigid body *Ball* traveling toward a static body *Box* at high speed. If the box uses a **ConcavePolygonShape3D** consisting of twelve triangle faces (two triangle faces for each of the six sides of the box), then the ball might end up inside the box or tunnel all the way through the box, if it goes fast enough. This is (partly) because the ball can only collide against the individual faces of the hollow box. In interactions with rigid bodies tunneling can be avoided by enabling continuous collision detection on the rigid body. - -\ **Warning:** Using this shape for an :ref:`Area3D` (via a :ref:`CollisionShape3D` node, created e.g. by using the *Create Trimesh Collision Sibling* option in the *Mesh* menu that appears when selecting a :ref:`MeshInstance3D` node) may give unexpected results: the area will only detect collisions with the triangle faces in the **ConcavePolygonShape3D** (and not with any "inside" of the shape, for example); moreover it will only detect all such collisions if :ref:`backface_collision` is ``true``. - -\ **Performance:** Due to its complexity, **ConcavePolygonShape3D** is the slowest collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, using :ref:`ConvexPolygonShape3D` will perform better. For dynamic physics bodies that need concave collision, several :ref:`ConvexPolygonShape3D`\ s can be used to represent its collision by using convex decomposition; see :ref:`ConvexPolygonShape3D`'s documentation for instructions. However, consider using primitive collision shapes such as :ref:`SphereShape3D` or :ref:`BoxShape3D` first. +\ **Performance:** Due to its complexity, **ConcavePolygonShape3D** is the slowest 3D collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, :ref:`ConvexPolygonShape3D` should be used. For dynamic physics bodies that need concave collision, several :ref:`ConvexPolygonShape3D`\ s can be used to represent its collision by using convex decomposition; see :ref:`ConvexPolygonShape3D`'s documentation for instructions. .. rst-class:: classref-introduction-group diff --git a/classes/class_conetwistjoint3d.rst b/classes/class_conetwistjoint3d.rst index 4a06f9c14d2..a59a8105781 100644 --- a/classes/class_conetwistjoint3d.rst +++ b/classes/class_conetwistjoint3d.rst @@ -12,18 +12,14 @@ ConeTwistJoint3D **Inherits:** :ref:`Joint3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -A twist joint between two 3D PhysicsBodies. +A physics joint that connects two 3D physics bodies in a way that simulates a ball-and-socket joint. .. rst-class:: classref-introduction-group Description ----------- -The joint can rotate the bodies across an axis defined by the local x-axes of the :ref:`Joint3D`. - -The twist axis is initiated as the X axis of the :ref:`Joint3D`. - -Once the Bodies swing, the twist axis is calculated as the middle of the x-axes of the Joint3D in the local space of the two Bodies. See also :ref:`Generic6DOFJoint3D`. +A physics joint that connects two 3D physics bodies in a way that simulates a ball-and-socket joint. The twist axis is initiated as the X axis of the **ConeTwistJoint3D**. Once the physics bodies swing, the twist axis is calculated as the middle of the X axes of the joint in the local space of the two physics bodies. Useful for limbs like shoulders and hips, lamps hanging off a ceiling, etc. .. rst-class:: classref-reftable-group diff --git a/classes/class_confirmationdialog.rst b/classes/class_confirmationdialog.rst index 7ab479c1d9b..d1c61ba2fc0 100644 --- a/classes/class_confirmationdialog.rst +++ b/classes/class_confirmationdialog.rst @@ -14,14 +14,14 @@ ConfirmationDialog **Inherited By:** :ref:`EditorCommandPalette`, :ref:`EditorFileDialog`, :ref:`FileDialog`, :ref:`ScriptCreateDialog` -Dialog for confirmation of actions. +A dialog used for confirmation of actions. .. rst-class:: classref-introduction-group Description ----------- -Dialog for confirmation of actions. This dialog inherits from :ref:`AcceptDialog`, but has by default an OK and Cancel button (in host OS order). +A dialog used for confirmation of actions. This window is similar to :ref:`AcceptDialog`, but pressing its Cancel button can have a different outcome from pressing the OK button. The order of the two buttons varies depending on the host OS. To get cancel action, you can use: diff --git a/classes/class_container.rst b/classes/class_container.rst index 19b40f838d4..cdf194f5166 100644 --- a/classes/class_container.rst +++ b/classes/class_container.rst @@ -14,23 +14,21 @@ Container **Inherited By:** :ref:`AspectRatioContainer`, :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`FlowContainer`, :ref:`GraphNode`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`SubViewportContainer`, :ref:`TabContainer` -Base node for containers. +Base class for all GUI containers. .. rst-class:: classref-introduction-group Description ----------- -Base node for containers. A **Container** contains other controls and automatically arranges them in a certain way. - -A Control can inherit this to create custom container classes. +Base class for all GUI containers. A **Container** automatically arranges its child controls in a certain way. This class can be inherited to make custom container types. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_control.rst b/classes/class_control.rst index c5d563fd2ba..b68e9086afc 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -14,7 +14,7 @@ Control **Inherited By:** :ref:`BaseButton`, :ref:`ColorRect`, :ref:`Container`, :ref:`GraphEdit`, :ref:`ItemList`, :ref:`Label`, :ref:`LineEdit`, :ref:`MenuBar`, :ref:`NinePatchRect`, :ref:`Panel`, :ref:`Range`, :ref:`ReferenceRect`, :ref:`RichTextLabel`, :ref:`Separator`, :ref:`TabBar`, :ref:`TextEdit`, :ref:`TextureRect`, :ref:`Tree`, :ref:`VideoStreamPlayer` -All user interface nodes inherit from Control. A control's anchors and offsets adapt its position and size relative to its parent. +Base class for all GUI controls. Adapts its position and size based on its parent control. .. rst-class:: classref-introduction-group @@ -1898,7 +1898,7 @@ This method should only be used to test the data. Process the data in :ref:`_dro { // Check position if it is relevant to you // Otherwise, just check data - return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().Contains("expected"); + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("expected"); } @@ -1930,7 +1930,7 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`_get_dra public override bool _CanDropData(Vector2 atPosition, Variant data) { - return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().Contains("color"); + return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().ContainsKey("color"); } public override void _DropData(Vector2 atPosition, Variant data) diff --git a/classes/class_convexpolygonshape2d.rst b/classes/class_convexpolygonshape2d.rst index 0d06c0eab26..b9bac56eb57 100644 --- a/classes/class_convexpolygonshape2d.rst +++ b/classes/class_convexpolygonshape2d.rst @@ -12,22 +12,20 @@ ConvexPolygonShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Convex polygon shape resource for 2D physics. +A 2D convex polygon shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D convex polygon shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. +A 2D convex polygon shape, intended for use in physics. Used internally in :ref:`CollisionPolygon2D` when it's in ``BUILD_SOLIDS`` mode. -The shape is a *solid* that includes all the points that it encloses, as opposed to :ref:`ConcavePolygonShape2D` which is hollow if it encloses anything. See also :ref:`CollisionPolygon2D`. +\ **ConvexPolygonShape2D** is *solid*, which means it detects collisions from objects that are fully inside it, unlike :ref:`ConcavePolygonShape2D` which is hollow. This makes it more suitable for both detection and physics. -The solid nature of the shape makes it well-suited for both detection and physics; in physics body interactions this allows depenetrating even those shapes which end up (e.g. due to high speed) fully inside the convex shape (similarly to primitive shapes, but unlike :ref:`ConcavePolygonShape2D`). The convexity limits the possible geometric shape of a single **ConvexPolygonShape2D**: it cannot be concave. +\ **Convex decomposition:** A concave polygon can be split up into several convex polygons. This allows dynamic physics bodies to have complex concave collisions (at a performance cost) and can be achieved by using several :ref:`ConvexPolygonShape3D` nodes or by using the :ref:`CollisionPolygon2D` node in ``BUILD_SOLIDS`` mode. To generate a collision polygon from a sprite, select the :ref:`Sprite2D` node, go to the **Sprite2D** menu that appears above the viewport, and choose **Create Polygon2D Sibling**. -\ **Convex decomposition:** Concave objects' collisions can be represented accurately using *several* convex shapes. This allows dynamic physics bodies to have complex concave collisions (at a performance cost). It can be achieved using several **ConvexPolygonShape2D** nodes or by using the :ref:`CollisionPolygon2D` node in Solids build mode. To generate a collision polygon from a sprite, select the :ref:`Sprite2D` node, go to the **Sprite2D** menu that appears above the viewport, and choose **Create Polygon2D Sibling**. - -\ **Performance:** **ConvexPolygonShape2D** is faster to check collisions against compared to :ref:`ConcavePolygonShape2D`, but it is slower than primitive collision shapes such as :ref:`CircleShape2D` or :ref:`RectangleShape2D`. Its use should generally be limited to medium-sized objects that cannot have their collision accurately represented by primitive shapes. +\ **Performance:** **ConvexPolygonShape2D** is faster to check collisions against compared to :ref:`ConcavePolygonShape2D`, but it is slower than primitive collision shapes such as :ref:`CircleShape2D` and :ref:`RectangleShape2D`. Its use should generally be limited to medium-sized objects that cannot have their collision accurately represented by primitive shapes. .. rst-class:: classref-reftable-group diff --git a/classes/class_convexpolygonshape3d.rst b/classes/class_convexpolygonshape3d.rst index a0f39a2a941..aeec2733152 100644 --- a/classes/class_convexpolygonshape3d.rst +++ b/classes/class_convexpolygonshape3d.rst @@ -12,22 +12,20 @@ ConvexPolygonShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Convex polygon shape resource for 3D physics. +A 3D convex polyhedron shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -3D convex polygon shape resource to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. +A 3D convex polyhedron shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. -The shape is a *solid* that includes all the points that it encloses, as opposed to :ref:`ConcavePolygonShape3D` which is hollow if it encloses anything. See also :ref:`CollisionPolygon3D`. +\ **ConvexPolygonShape3D** is *solid*, which means it detects collisions from objects that are fully inside it, unlike :ref:`ConcavePolygonShape3D` which is hollow. This makes it more suitable for both detection and physics. -The solid nature of the shape makes it well-suited for both detection and physics; in physics body interactions this allows depenetrating even those shapes which end up (e.g. due to high speed) fully inside the convex shape (similarly to primitive shapes, but unlike :ref:`ConcavePolygonShape3D` and :ref:`HeightMapShape3D`). The convexity restricts the possible geometric shape of a single **ConvexPolygonShape3D**: it cannot be concave. +\ **Convex decomposition:** A concave polyhedron can be split up into several convex polyhedra. This allows dynamic physics bodies to have complex concave collisions (at a performance cost) and can be achieved by using several **ConvexPolygonShape3D** nodes. To generate a convex decomposition from a mesh, select the :ref:`MeshInstance3D` node, go to the **Mesh** menu that appears above the viewport, and choose **Create Multiple Convex Collision Siblings**. Alternatively, :ref:`MeshInstance3D.create_multiple_convex_collisions` can be called in a script to perform this decomposition at run-time. -\ **Convex decomposition:** Concave objects' collisions can be represented accurately using *several* convex shapes. This allows dynamic physics bodies to have complex concave collisions (at a performance cost). It can be achieved by using several **ConvexPolygonShape3D** nodes or by using the :ref:`CollisionPolygon3D` node. To generate a collision polygon from a mesh, select the :ref:`MeshInstance3D` node, go to the **Mesh** menu that appears above the viewport and choose **Create Multiple Convex Collision Siblings**. Alternatively, :ref:`MeshInstance3D.create_multiple_convex_collisions` can be called in a script to perform this decomposition at run-time. - -\ **Performance:** **ConvexPolygonShape3D** is faster to check collisions against compared to :ref:`ConcavePolygonShape3D`, but it is slower than primitive collision shapes such as :ref:`SphereShape3D` or :ref:`BoxShape3D`. Its use should generally be limited to medium-sized objects that cannot have their collision accurately represented by primitive shapes. +\ **Performance:** **ConvexPolygonShape3D** is faster to check collisions against compared to :ref:`ConcavePolygonShape3D`, but it is slower than primitive collision shapes such as :ref:`SphereShape3D` and :ref:`BoxShape3D`. Its use should generally be limited to medium-sized objects that cannot have their collision accurately represented by primitive shapes. .. rst-class:: classref-introduction-group diff --git a/classes/class_crypto.rst b/classes/class_crypto.rst index a808cc1a61b..30d78589c98 100644 --- a/classes/class_crypto.rst +++ b/classes/class_crypto.rst @@ -12,16 +12,16 @@ Crypto **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Access to advanced cryptographic functionalities. +Provides access to advanced cryptographic functionalities. .. rst-class:: classref-introduction-group Description ----------- -The Crypto class allows you to access some more advanced cryptographic functionalities in Godot. +The Crypto class provides access to advanced cryptographic functionalities. -For now, this includes generating cryptographically secure random bytes, RSA keys and self-signed X509 certificates generation, asymmetric key encryption/decryption, and signing/verification. +Currently, this includes asymmetric key encryption/decryption, signing/verification, and generating cryptographically secure random bytes, RSA keys, HMAC digests, and self-signed :ref:`X509Certificate`\ s. .. tabs:: diff --git a/classes/class_cylindershape3d.rst b/classes/class_cylindershape3d.rst index 7bb50c0dc2e..45a6a9fded0 100644 --- a/classes/class_cylindershape3d.rst +++ b/classes/class_cylindershape3d.rst @@ -12,18 +12,18 @@ CylinderShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Cylinder shape for 3D collisions. +A 3D cylinder shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -Cylinder shape for collisions. Like :ref:`CapsuleShape3D`, but without hemispheres at the cylinder's ends. +A 2D capsule shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. \ **Note:** There are several known bugs with cylinder collision shapes. Using :ref:`CapsuleShape3D` or :ref:`BoxShape3D` instead is recommended. -\ **Performance:** Being a primitive collision shape, **CylinderShape3D** is fast to check collisions against (though not as fast as :ref:`SphereShape3D`). **CylinderShape3D** is also more demanding compared to :ref:`CapsuleShape3D`. +\ **Performance:** **CylinderShape3D** is fast to check collisions against, but it is slower than :ref:`CapsuleShape3D`, :ref:`BoxShape3D`, and **CylinderShape3D**. .. rst-class:: classref-introduction-group diff --git a/classes/class_dampedspringjoint2d.rst b/classes/class_dampedspringjoint2d.rst index ef1a58c0c2f..86d9137161a 100644 --- a/classes/class_dampedspringjoint2d.rst +++ b/classes/class_dampedspringjoint2d.rst @@ -12,14 +12,14 @@ DampedSpringJoint2D **Inherits:** :ref:`Joint2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Damped spring constraint for 2D physics. +A physics joint that connects two 2D physics bodies with a spring-like force. .. rst-class:: classref-introduction-group Description ----------- -Damped spring constraint for 2D physics. This resembles a spring joint that always wants to go back to a given length. +A physics joint that connects two 2D physics bodies with a spring-like force. This resembles a spring that always wants to stretch to a given length. .. rst-class:: classref-reftable-group diff --git a/classes/class_dictionary.rst b/classes/class_dictionary.rst index 7e2f971f6fa..fe6c63adf5f 100644 --- a/classes/class_dictionary.rst +++ b/classes/class_dictionary.rst @@ -10,18 +10,16 @@ Dictionary ========== -Dictionary type. +A built-in data structure that holds key-value pairs. .. rst-class:: classref-introduction-group Description ----------- -Dictionary type. Associative container, which contains values referenced by unique keys. Dictionaries are composed of pairs of keys (which must be unique) and values. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is sometimes referred to as a hash map or associative array. +Dictionaries are associative containers that contain values referenced by unique keys. Dictionaries will preserve the insertion order when adding new entries. In other programming languages, this data structure is often referred to as a hash map or an associative array. -You can define a dictionary by placing a comma-separated list of ``key: value`` pairs in curly braces ``{}``. - -\ **Note:** Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use :ref:`duplicate`. +You can define a dictionary by placing a comma-separated list of ``key: value`` pairs inside curly braces ``{}``. Creating a dictionary: @@ -187,6 +185,8 @@ The keys of a dictionary can be iterated with the ``for`` keyword: +\ **Note:** Dictionaries are always passed by reference. To get a copy of a dictionary which can be modified independently of the original dictionary, use :ref:`duplicate`. + \ **Note:** Erasing elements while iterating over dictionaries is **not** supported and will result in unpredictable behavior. .. rst-class:: classref-introduction-group @@ -400,9 +400,9 @@ Returns ``true`` if the dictionary contains an entry with the given ``key``. { 210, default }, }; - GD.Print(myDict.Contains("Godot")); // Prints true - GD.Print(myDict.Contains(210)); // Prints true - GD.Print(myDict.Contains(4)); // Prints false + GD.Print(myDict.ContainsKey("Godot")); // Prints true + GD.Print(myDict.ContainsKey(210)); // Prints true + GD.Print(myDict.ContainsKey(4)); // Prints false diff --git a/classes/class_diraccess.rst b/classes/class_diraccess.rst index a6b58cbb168..a42aabc0158 100644 --- a/classes/class_diraccess.rst +++ b/classes/class_diraccess.rst @@ -12,14 +12,14 @@ DirAccess **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Type used to handle the filesystem. +Provides methods for managing directories and their content. .. rst-class:: classref-introduction-group Description ----------- -Directory type. It is used to manage directories and their content (not restricted to the project folder). +This class is used to manage directories and their content, even outside of the project folder. \ **DirAccess** can't be instantiated directly. Instead it is created with a static method that takes a path for which it will be opened. @@ -417,7 +417,7 @@ Returns a :ref:`PackedStringArray` containing filenames Affected by :ref:`include_hidden`. -\ **Note:** When used on a ``res://`` path in an exported project, only the files actually included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level ``.godot/`` folder, only paths to ``*.gd`` and ``*.import`` files are returned (plus a few files such as ``project.godot`` or ``project.binary[code] and the project icon). In an exported project, the list of returned files will also vary depending on whether [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true``. +\ **Note:** When used on a ``res://`` path in an exported project, only the files actually included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level ``.godot/`` folder, only paths to ``*.gd`` and ``*.import`` files are returned (plus a few files such as ``project.godot`` or ``project.binary`` and the project icon). In an exported project, the list of returned files will also vary depending on whether :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` is ``true``. .. rst-class:: classref-item-separator diff --git a/classes/class_displayserver.rst b/classes/class_displayserver.rst index 59a7833466d..4551dcff910 100644 --- a/classes/class_displayserver.rst +++ b/classes/class_displayserver.rst @@ -12,14 +12,14 @@ DisplayServer **Inherits:** :ref:`Object` -Singleton for window management functions. +A server interface for low-level window management. .. rst-class:: classref-introduction-group Description ----------- -**DisplayServer** handles everything related to window management. This is separated from :ref:`OS` as a single operating system may support multiple display servers. +**DisplayServer** handles everything related to window management. It is separated from :ref:`OS` as a single operating system may support multiple display servers. \ **Headless mode:** Starting the engine with the ``--headless`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>` disables all rendering and window management functions. Most functions from **DisplayServer** will return dummy values in this case. @@ -758,7 +758,7 @@ I-beam cursor shape. This is used by default when hovering a control that accept :ref:`CursorShape` **CURSOR_POINTING_HAND** = ``2`` -Pointing hand cursor shape. This is used by default when hovering a :ref:`LinkButton` or an URL tag in a :ref:`RichTextLabel`. +Pointing hand cursor shape. This is used by default when hovering a :ref:`LinkButton` or a URL tag in a :ref:`RichTextLabel`. .. _class_DisplayServer_constant_CURSOR_CROSS: @@ -1018,7 +1018,7 @@ Use :ref:`window_set_window_buttons_offset` to determine area under the title bar that is not covered by decorations. -\ **Note:** This flag is implemented on macOS. +\ **Note:** This flag is implemented only on macOS. .. _class_DisplayServer_constant_WINDOW_FLAG_MOUSE_PASSTHROUGH: @@ -1094,7 +1094,7 @@ Sent when the user has attempted to close the window (e.g. close button is press Sent when the device "Back" button is pressed, see :ref:`window_set_window_event_callback`. -\ **Note:** This event is implemented on Android. +\ **Note:** This event is implemented only on Android. .. _class_DisplayServer_constant_WINDOW_EVENT_DPI_CHANGE: @@ -1104,7 +1104,7 @@ Sent when the device "Back" button is pressed, see :ref:`window_set_window_event Sent when the window is moved to the display with different DPI, or display DPI is changed, see :ref:`window_set_window_event_callback`. -\ **Note:** This flag is implemented on macOS. +\ **Note:** This flag is implemented only on macOS. .. _class_DisplayServer_constant_WINDOW_EVENT_TITLEBAR_CHANGE: @@ -1114,7 +1114,7 @@ Sent when the window is moved to the display with different DPI, or display DPI Sent when the window title bar decoration is changed (e.g. :ref:`WINDOW_FLAG_EXTEND_TO_TITLE` is set or window entered/exited full screen mode), see :ref:`window_set_window_event_callback`. -\ **Note:** This flag is implemented on macOS. +\ **Note:** This flag is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1446,7 +1446,7 @@ Sets the default mouse cursor shape. The cursor's appearance will vary depending Shows a text input dialog which uses the operating system's native look-and-feel. ``callback`` will be called with a :ref:`String` argument equal to the text field's contents when the dialog is closed for any reason. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1460,7 +1460,7 @@ Shows a text input dialog which uses the operating system's native look-and-feel Shows a text dialog which uses the operating system's native look-and-feel. ``callback`` will be called when the dialog is closed for any reason. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1474,7 +1474,7 @@ void **enable_for_stealing_focus** **(** :ref:`int` process_id **)** Allows the ``process_id`` PID to steal focus from this window. In other words, this disables the operating system's focus stealing protection for the specified PID. -\ **Note:** This method is implemented on Windows. +\ **Note:** This method is implemented only on Windows. .. rst-class:: classref-item-separator @@ -1659,7 +1659,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1686,7 +1686,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1713,7 +1713,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1742,7 +1742,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1769,7 +1769,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1800,7 +1800,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1829,7 +1829,7 @@ An ``accelerator`` can optionally be defined, which is a keyboard shortcut that \ **Note:** The ``callback`` and ``key_callback`` Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to ``tag``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1852,7 +1852,7 @@ Adds a separator between items to the global menu with ID ``menu_root``. Separat Returns index of the inserted item, it's not guaranteed to be the same as ``index`` value. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1875,7 +1875,7 @@ Adds an item that will act as a submenu of the global menu ``menu_root``. The `` Returns index of the inserted item, it's not guaranteed to be the same as ``index`` value. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1896,7 +1896,7 @@ void **global_menu_clear** **(** :ref:`String` menu_root **)** Removes all items from the global menu with ID ``menu_root``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Supported system menu IDs:**\ @@ -1917,7 +1917,7 @@ Removes all items from the global menu with ID ``menu_root``. Returns the accelerator of the item at index ``idx``. Accelerators are special combinations of keys that activate the item, no matter which control is focused. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1931,7 +1931,7 @@ Returns the accelerator of the item at index ``idx``. Accelerators are special c Returns the callback of the item at index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1945,7 +1945,7 @@ Returns the callback of the item at index ``idx``. Returns number of items in the global menu with ID ``menu_root``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1959,7 +1959,7 @@ Returns number of items in the global menu with ID ``menu_root``. Returns the icon of the item at index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1973,7 +1973,7 @@ Returns the icon of the item at index ``idx``. Returns the horizontal offset of the item at the given ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -1987,7 +1987,7 @@ Returns the horizontal offset of the item at the given ``idx``. Returns the index of the item with the specified ``tag``. Index is automatically assigned to each item by the engine. Index can not be set manually. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2001,7 +2001,7 @@ Returns the index of the item with the specified ``tag``. Index is automatically Returns the index of the item with the specified ``text``. Index is automatically assigned to each item by the engine. Index can not be set manually. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2015,7 +2015,7 @@ Returns the index of the item with the specified ``text``. Index is automaticall Returns the callback of the item accelerator at index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2029,7 +2029,7 @@ Returns the callback of the item accelerator at index ``idx``. Returns number of states of a multistate item. See :ref:`global_menu_add_multistate_item` for details. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2043,7 +2043,7 @@ Returns number of states of a multistate item. See :ref:`global_menu_add_multist Returns the state of a multistate item. See :ref:`global_menu_add_multistate_item` for details. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2057,7 +2057,7 @@ Returns the state of a multistate item. See :ref:`global_menu_add_multistate_ite Returns the submenu ID of the item at index ``idx``. See :ref:`global_menu_add_submenu_item` for more info on how to add a submenu. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2071,7 +2071,7 @@ Returns the submenu ID of the item at index ``idx``. See :ref:`global_menu_add_s Returns the metadata of the specified item, which might be of any type. You can set it with :ref:`global_menu_set_item_tag`, which provides a simple way of assigning context data to items. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2085,7 +2085,7 @@ Returns the metadata of the specified item, which might be of any type. You can Returns the text of the item at index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2099,7 +2099,7 @@ Returns the text of the item at index ``idx``. Returns the tooltip associated with the specified index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2113,7 +2113,7 @@ Returns the tooltip associated with the specified index ``idx``. Returns ``true`` if the item at index ``idx`` is checkable in some way, i.e. if it has a checkbox or radio button. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2127,7 +2127,7 @@ Returns ``true`` if the item at index ``idx`` is checkable in some way, i.e. if Returns ``true`` if the item at index ``idx`` is checked. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2143,7 +2143,7 @@ Returns ``true`` if the item at index ``idx`` is disabled. When it is disabled i See :ref:`global_menu_set_item_disabled` for more info on how to disable an item. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2159,7 +2159,7 @@ Returns ``true`` if the item at index ``idx`` has radio button-style checkabilit \ **Note:** This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2175,7 +2175,7 @@ Removes the item at index ``idx`` from the global menu ``menu_root``. \ **Note:** The indices of items after the removed item will be shifted by one. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2189,7 +2189,7 @@ void **global_menu_set_item_accelerator** **(** :ref:`String` menu Sets the accelerator of the item at index ``idx``. ``keycode`` can be a single :ref:`Key`, or a combination of :ref:`KeyModifierMask`\ s and :ref:`Key`\ s using bitwise OR such as ``KEY_MASK_CTRL | KEY_A`` (:kbd:`Ctrl + A`). -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2205,7 +2205,7 @@ Sets the callback of the item at index ``idx``. Callback is emitted when an item \ **Note:** The ``callback`` Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the ``tag`` parameter when the menu item was created. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2219,7 +2219,7 @@ void **global_menu_set_item_checkable** **(** :ref:`String` menu_r Sets whether the item at index ``idx`` has a checkbox. If ``false``, sets the type of the item to plain text. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2233,7 +2233,7 @@ void **global_menu_set_item_checked** **(** :ref:`String` menu_roo Sets the checkstate status of the item at index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2247,7 +2247,7 @@ void **global_menu_set_item_disabled** **(** :ref:`String` menu_ro Enables/disables the item at index ``idx``. When it is disabled, it can't be selected and its action can't be invoked. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2261,7 +2261,7 @@ void **global_menu_set_item_icon** **(** :ref:`String` menu_root, Replaces the :ref:`Texture2D` icon of the specified ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. \ **Note:** This method is not supported by macOS "_dock" menu items. @@ -2277,7 +2277,7 @@ void **global_menu_set_item_indentation_level** **(** :ref:`String Sets the horizontal offset of the item at the given ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2293,7 +2293,7 @@ Sets the callback of the item at index ``idx``. Callback is emitted when its acc \ **Note:** The ``key_callback`` Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the ``tag`` parameter when the menu item was created. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2307,7 +2307,7 @@ void **global_menu_set_item_max_states** **(** :ref:`String` menu_ Sets number of state of a multistate item. See :ref:`global_menu_add_multistate_item` for details. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2323,7 +2323,7 @@ Sets the type of the item at the specified index ``idx`` to radio button. If ``f \ **Note:** This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2337,7 +2337,7 @@ void **global_menu_set_item_state** **(** :ref:`String` menu_root, Sets the state of a multistate item. See :ref:`global_menu_add_multistate_item` for details. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2351,7 +2351,7 @@ void **global_menu_set_item_submenu** **(** :ref:`String` menu_roo Sets the submenu of the item at index ``idx``. The submenu is the ID of a global menu root that would be shown when the item is clicked. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2365,7 +2365,7 @@ void **global_menu_set_item_tag** **(** :ref:`String` menu_root, : Sets the metadata of an item, which may be of any type. You can later get it with :ref:`global_menu_get_item_tag`, which provides a simple way of assigning context data to items. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2379,7 +2379,7 @@ void **global_menu_set_item_text** **(** :ref:`String` menu_root, Sets the text of the item at index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2393,7 +2393,7 @@ void **global_menu_set_item_tooltip** **(** :ref:`String` menu_roo Sets the :ref:`String` tooltip of the item at the specified index ``idx``. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2419,7 +2419,7 @@ Returns ``true`` if the specified ``feature`` is supported by the current **Disp Returns the text selection in the `Input Method Editor `__ composition string, with the :ref:`Vector2i`'s ``x`` component being the caret position and ``y`` being the length of the selection. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2433,7 +2433,7 @@ Returns the text selection in the `Input Method Editor `__ window. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2676,7 +2676,7 @@ Returns the greatest scale factor of all screens. \ **Note:** On macOS returned value is ``2.0`` if there is at least one hiDPI (Retina) screen in the system, and ``1.0`` in all other cases. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2767,7 +2767,7 @@ Returns the scale factor of the specified screen by index. \ **Note:** On macOS returned value is ``2.0`` for hiDPI (Retina) screen, and ``1.0`` for all other cases. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -2865,7 +2865,7 @@ Sets the window icon (usually displayed in the top-left corner) in the operating Returns current active tablet driver name. -\ **Note:** This method is implemented on Windows. +\ **Note:** This method is implemented only on Windows. .. rst-class:: classref-item-separator @@ -2879,7 +2879,7 @@ Returns current active tablet driver name. Returns the total number of available tablet drivers. -\ **Note:** This method is implemented on Windows. +\ **Note:** This method is implemented only on Windows. .. rst-class:: classref-item-separator @@ -2893,7 +2893,7 @@ Returns the total number of available tablet drivers. Returns the tablet driver name for the given index. -\ **Note:** This method is implemented on Windows. +\ **Note:** This method is implemented only on Windows. .. rst-class:: classref-item-separator @@ -2907,7 +2907,7 @@ void **tablet_set_current_driver** **(** :ref:`String` name **)** Set active tablet driver name. -\ **Note:** This method is implemented on Windows. +\ **Note:** This method is implemented only on Windows. .. rst-class:: classref-item-separator @@ -3181,7 +3181,7 @@ Returns ID of the active popup window, or :ref:`INVALID_WINDOW_ID` **window_get_attached_instance_id** **(** :ref:`int` window_id=0 **)** |const| -Returns the :ref:`Object.get_instance_id` of the :ref:`Window` the ``window_id`` is attached to. also :ref:`window_get_attached_instance_id`. +Returns the :ref:`Object.get_instance_id` of the :ref:`Window` the ``window_id`` is attached to. .. rst-class:: classref-item-separator @@ -3365,7 +3365,7 @@ Returns ``true`` if the given window can be maximized (the maximize button is en Returns ``true``, if double-click on a window title should maximize it. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -3379,7 +3379,7 @@ Returns ``true``, if double-click on a window title should maximize it. Returns ``true``, if double-click on a window title should minimize it. -\ **Note:** This method is implemented on macOS. +\ **Note:** This method is implemented only on macOS. .. rst-class:: classref-item-separator @@ -3725,7 +3725,7 @@ void **window_set_window_buttons_offset** **(** :ref:`Vector2i` When :ref:`WINDOW_FLAG_EXTEND_TO_TITLE` flag is set, set offset to the center of the first titlebar button. -\ **Note:** This flag is implemented on macOS. +\ **Note:** This flag is implemented only on macOS. .. rst-class:: classref-item-separator diff --git a/classes/class_editorfiledialog.rst b/classes/class_editorfiledialog.rst index 0715ea7dd00..34cecd55025 100644 --- a/classes/class_editorfiledialog.rst +++ b/classes/class_editorfiledialog.rst @@ -19,7 +19,7 @@ A modified version of :ref:`FileDialog` used by the editor. Description ----------- -**EditorFileDialog** is an enhanced version of :ref:`FileDialog` available only to editor plugins. Additional features include list of favorited/recent files and ability to see files as thumbnails grid instead of list. +**EditorFileDialog** is an enhanced version of :ref:`FileDialog` available only to editor plugins. Additional features include list of favorited/recent files and the ability to see files as thumbnails grid instead of list. .. rst-class:: classref-reftable-group diff --git a/classes/class_editorimportplugin.rst b/classes/class_editorimportplugin.rst index babd4362e32..4dbc9ade898 100644 --- a/classes/class_editorimportplugin.rst +++ b/classes/class_editorimportplugin.rst @@ -115,7 +115,7 @@ Below is an example EditorImportPlugin that imports a :ref:`Mesh` fr new Godot.Collections.Dictionary { { "name", "myOption" }, - { "defaultValue", false }, + { "default_value", false }, } }; } @@ -249,12 +249,12 @@ This method can be overridden to hide specific import options if conditions are .. code-tab:: csharp - public void GetOptionVisibility(string option, Godot.Collections.Dictionary options) + public void _GetOptionVisibility(string option, Godot.Collections.Dictionary options) { // Only show the lossy quality setting if the compression mode is set to "Lossy". - if (option == "compress/lossyQuality" && options.Contains("compress/mode")) + if (option == "compress/lossy_quality" && options.ContainsKey("compress/mode")) { - return (int)options["compress/mode"] == COMPRESS_LOSSY; // This is a constant you set + return (int)options["compress/mode"] == CompressLossy; // This is a constant you set } return true; diff --git a/classes/class_editorinterface.rst b/classes/class_editorinterface.rst index 2c8cf444bce..0a68c6d0843 100644 --- a/classes/class_editorinterface.rst +++ b/classes/class_editorinterface.rst @@ -19,7 +19,7 @@ Godot editor's interface. Description ----------- -EditorInterface gives you control over Godot editor's window. It allows customizing the window, saving and (re-)loading scenes, rendering mesh previews, inspecting and editing resources and objects, and provides access to :ref:`EditorSettings`, :ref:`EditorFileSystem`, :ref:`EditorResourcePreview`, :ref:`ScriptEditor`, the editor viewport, and information about scenes. +**EditorInterface** gives you control over Godot editor's window. It allows customizing the window, saving and (re-)loading scenes, rendering mesh previews, inspecting and editing resources and objects, and provides access to :ref:`EditorSettings`, :ref:`EditorFileSystem`, :ref:`EditorResourcePreview`, :ref:`ScriptEditor`, the editor viewport, and information about scenes. \ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorPlugin.get_editor_interface`. diff --git a/classes/class_editornode3dgizmoplugin.rst b/classes/class_editornode3dgizmoplugin.rst index c75964bdb9c..786f2010410 100644 --- a/classes/class_editornode3dgizmoplugin.rst +++ b/classes/class_editornode3dgizmoplugin.rst @@ -12,7 +12,7 @@ EditorNode3DGizmoPlugin **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Used by the editor to define Node3D gizmo types. +A class used by the editor to define Node3D gizmo types. .. rst-class:: classref-introduction-group diff --git a/classes/class_editorproperty.rst b/classes/class_editorproperty.rst index 8cb02a9f0a2..a5ff52a2098 100644 --- a/classes/class_editorproperty.rst +++ b/classes/class_editorproperty.rst @@ -12,14 +12,14 @@ EditorProperty **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Custom control to edit properties for adding into the inspector. +Custom control for editing properties that can be added to the :ref:`EditorInspector`. .. rst-class:: classref-introduction-group Description ----------- -This control allows property editing for one or multiple properties into :ref:`EditorInspector`. It is added via :ref:`EditorInspectorPlugin`. +A custom control for editing properties that can be added to the :ref:`EditorInspector`. It is added via :ref:`EditorInspectorPlugin`. .. rst-class:: classref-reftable-group diff --git a/classes/class_editorresourcepreview.rst b/classes/class_editorresourcepreview.rst index 249921c4f9c..d7f89c79b6b 100644 --- a/classes/class_editorresourcepreview.rst +++ b/classes/class_editorresourcepreview.rst @@ -12,14 +12,14 @@ EditorResourcePreview **Inherits:** :ref:`Node` **<** :ref:`Object` -Helper to generate previews of resources or files. +A node used to generate previews of resources or files. .. rst-class:: classref-introduction-group Description ----------- -This object is used to generate previews for resources of files. +This node is used to generate previews for resources of files. \ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_resource_previewer`. diff --git a/classes/class_editorresourcetooltipplugin.rst b/classes/class_editorresourcetooltipplugin.rst index c9c66e1c2f3..d4a7ad3cd52 100644 --- a/classes/class_editorresourcetooltipplugin.rst +++ b/classes/class_editorresourcetooltipplugin.rst @@ -31,15 +31,13 @@ Methods .. table:: :widths: auto - +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`_handles` **(** :ref:`String` type **)** |virtual| |const| | - +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Object` | :ref:`_make_tooltip_for_path` **(** :ref:`String` path, :ref:`Dictionary` metadata **)** |virtual| |const| | - +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`VBoxContainer` | :ref:`make_default_tooltip` **(** :ref:`String` path **)** |static| | - +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | void | :ref:`request_thumbnail` **(** :ref:`String` path, :ref:`TextureRect` control **)** |const| | - +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_handles` **(** :ref:`String` type **)** |virtual| |const| | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Control` | :ref:`_make_tooltip_for_path` **(** :ref:`String` path, :ref:`Dictionary` metadata, :ref:`Control` base **)** |virtual| |const| | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`request_thumbnail` **(** :ref:`String` path, :ref:`TextureRect` control **)** |const| | + +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -66,25 +64,25 @@ Return ``true`` if the plugin is going to handle the given :ref:`Resource` **_make_tooltip_for_path** **(** :ref:`String` path, :ref:`Dictionary` metadata **)** |virtual| |const| +:ref:`Control` **_make_tooltip_for_path** **(** :ref:`String` path, :ref:`Dictionary` metadata, :ref:`Control` base **)** |virtual| |const| -Create and return a tooltip that will be displayed when the user hovers resource under given ``path`` in filesystem dock. For best results, use :ref:`make_default_tooltip` as a base. +Create and return a tooltip that will be displayed when the user hovers a resource under the given ``path`` in filesystem dock. The ``metadata`` dictionary is provided by preview generator (see method EditorResourcePreviewGenerator._generate]). -\ **Note:** It's unadvised to use :ref:`ResourceLoader.load`, especially with heavy resources like models or textures, because it will make the editor unresponsive when creating the tooltip. You can use :ref:`request_thumbnail` if you want to display a preview in your tooltip. - -.. rst-class:: classref-item-separator +\ ``base`` is the base default tooltip, which is a :ref:`VBoxContainer` with a file name, type and size labels. If another plugin handled the same file type, ``base`` will be output from the previous plugin. For best result, make sure the base tooltip is part of the returned :ref:`Control`. ----- - -.. _class_EditorResourceTooltipPlugin_method_make_default_tooltip: +\ **Note:** It's unadvised to use :ref:`ResourceLoader.load`, especially with heavy resources like models or textures, because it will make the editor unresponsive when creating the tooltip. You can use :ref:`request_thumbnail` if you want to display a preview in your tooltip. -.. rst-class:: classref-method +\ **Note:** If you decide to discard the ``base``, make sure to call :ref:`Node.queue_free`, because it's not freed automatically. -:ref:`VBoxContainer` **make_default_tooltip** **(** :ref:`String` path **)** |static| +:: -Creates a default file tooltip. The tooltip includes file name, file size and :ref:`Resource` type if available. + func _make_tooltip_for_path(path, metadata, base): + var t_rect = TextureRect.new() + request_thumbnail(path, t_rect) + base.add_child(t_rect) # The TextureRect will appear at the bottom of the tooltip. + return base .. rst-class:: classref-item-separator diff --git a/classes/class_editorsettings.rst b/classes/class_editorsettings.rst index a259033ff75..7a40b941d16 100644 --- a/classes/class_editorsettings.rst +++ b/classes/class_editorsettings.rst @@ -89,8 +89,6 @@ Properties +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`editors/2d/bone_width` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`editors/2d/constrain_editor_view` | - +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`editors/2d/grid_color` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`editors/2d/guides_color` | @@ -395,8 +393,6 @@ Properties +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/appearance/gutters/line_numbers_zero_padded` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`text_editor/appearance/gutters/show_bookmark_gutter` | - +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/appearance/gutters/show_info_gutter` | +-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`text_editor/appearance/gutters/show_line_numbers` | @@ -813,18 +809,6 @@ The bone width in the 2D skeleton editor (in pixels). See also :ref:`editors/2d/ ---- -.. _class_EditorSettings_property_editors/2d/constrain_editor_view: - -.. rst-class:: classref-property - -:ref:`bool` **editors/2d/constrain_editor_view** - -If ``true``, prevents the 2D editor viewport from leaving the scene. Limits are calculated dynamically based on nodes present in the current scene. If ``false``, the 2D editor viewport will be able to move freely, but you risk getting lost when zooming out too far. You can refocus on the scene by selecting a node then pressing :kbd:`F`. - -.. rst-class:: classref-item-separator - ----- - .. _class_EditorSettings_property_editors/2d/grid_color: .. rst-class:: classref-property @@ -2753,25 +2737,13 @@ If ``true``, displays line numbers with zero padding (e.g. ``007`` instead of `` ---- -.. _class_EditorSettings_property_text_editor/appearance/gutters/show_bookmark_gutter: - -.. rst-class:: classref-property - -:ref:`bool` **text_editor/appearance/gutters/show_bookmark_gutter** - -If ``true``, displays icons for bookmarks in a gutter at the left. Bookmarks remain functional when this setting is disabled. - -.. rst-class:: classref-item-separator - ----- - .. _class_EditorSettings_property_text_editor/appearance/gutters/show_info_gutter: .. rst-class:: classref-property :ref:`bool` **text_editor/appearance/gutters/show_info_gutter** -If ``true``, displays a gutter at the left containing icons for methods with signal connections. +If ``true``, displays a gutter at the left containing icons for methods with signal connections and for overridden methods. .. rst-class:: classref-item-separator diff --git a/classes/class_editorsyntaxhighlighter.rst b/classes/class_editorsyntaxhighlighter.rst index 17b9f482ca9..6357b895f19 100644 --- a/classes/class_editorsyntaxhighlighter.rst +++ b/classes/class_editorsyntaxhighlighter.rst @@ -12,14 +12,14 @@ EditorSyntaxHighlighter **Inherits:** :ref:`SyntaxHighlighter` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Base Syntax highlighter resource for the :ref:`ScriptEditor`. +Base class for :ref:`SyntaxHighlighter` used by the :ref:`ScriptEditor`. .. rst-class:: classref-introduction-group Description ----------- -Base syntax highlighter resource all editor syntax highlighters extend from, it is used in the :ref:`ScriptEditor`. +Base class that all :ref:`SyntaxHighlighter`\ s used by the :ref:`ScriptEditor` extend from. Add a syntax highlighter to an individual script by calling :ref:`ScriptEditorBase.add_syntax_highlighter`. To apply to all scripts on open, call :ref:`ScriptEditor.register_syntax_highlighter` diff --git a/classes/class_engine.rst b/classes/class_engine.rst index 7c4ec586704..ce6b666ea91 100644 --- a/classes/class_engine.rst +++ b/classes/class_engine.rst @@ -12,7 +12,7 @@ Engine **Inherits:** :ref:`Object` -Access to engine properties. +Provides access to engine properties. .. rst-class:: classref-introduction-group diff --git a/classes/class_fileaccess.rst b/classes/class_fileaccess.rst index 876b8148981..4cf9c3c4e26 100644 --- a/classes/class_fileaccess.rst +++ b/classes/class_fileaccess.rst @@ -12,14 +12,14 @@ FileAccess **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Type to handle file reading and writing operations. +Provides methods for file reading and writing operations. .. rst-class:: classref-introduction-group Description ----------- -File type. This is used to permanently store data into the user device's file system and to read from it. This can be used to store game save data or player configuration files, for example. +This class can be used to permanently store data in the user device's file system and to read from it. This is useful for store game save data or player configuration files. Here's a sample on how to write and read from a file: @@ -56,24 +56,9 @@ Here's a sample on how to write and read from a file: In the example above, the file will be saved in the user data folder as specified in the :doc:`Data paths <../tutorials/io/data_paths>` documentation. -\ **FileAccess** will close when it's freed, which happens when it goes out of scope or when it gets assigned with ``null``. In C# the reference must be disposed after we are done using it, this can be done with the ``using`` statement or calling the ``Dispose`` method directly. +\ **FileAccess** will close when it's freed, which happens when it goes out of scope or when it gets assigned with ``null``. :ref:`close` can be used to close it before then explicitly. In C# the reference must be disposed manually, which can be done with the ``using`` statement or by calling the ``Dispose`` method directly. - -.. tabs:: - - .. code-tab:: gdscript - - var file = FileAccess.open("res://something") # File is opened and locked for use. - file = null # File is closed. - - .. code-tab:: csharp - - using var file = FileAccess.Open("res://something"); // File is opened and locked for use. - // The using statement calls Dispose when going out of scope. - - - -\ **Note:** To access project resources once exported, it is recommended to use :ref:`ResourceLoader` instead of the **FileAccess** API, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. +\ **Note:** To access project resources once exported, it is recommended to use :ref:`ResourceLoader` instead of **FileAccess**, as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. \ **Note:** Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing **Alt + F4**). If you stop the project execution by pressing **F8** while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling :ref:`flush` at regular intervals. diff --git a/classes/class_filedialog.rst b/classes/class_filedialog.rst index 9ab009a9158..1b0dd2ecdc0 100644 --- a/classes/class_filedialog.rst +++ b/classes/class_filedialog.rst @@ -12,14 +12,14 @@ FileDialog **Inherits:** :ref:`ConfirmationDialog` **<** :ref:`AcceptDialog` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -Dialog for selecting files or directories in the filesystem. +A dialog for selecting files or directories in the filesystem. .. rst-class:: classref-introduction-group Description ----------- -FileDialog is a preset dialog used to choose files and directories in the filesystem. It supports filter masks. The FileDialog automatically sets its window title according to the :ref:`file_mode`. If you want to use a custom title, disable this by setting :ref:`mode_overrides_title` to ``false``. +**FileDialog** is a preset dialog used to choose files and directories in the filesystem. It supports filter masks. **FileDialog** automatically sets its window title according to the :ref:`file_mode`. If you want to use a custom title, disable this by setting :ref:`mode_overrides_title` to ``false``. .. rst-class:: classref-reftable-group diff --git a/classes/class_filesystemdock.rst b/classes/class_filesystemdock.rst index f67b2eb41ca..b98c8de8a87 100644 --- a/classes/class_filesystemdock.rst +++ b/classes/class_filesystemdock.rst @@ -12,7 +12,7 @@ FileSystemDock **Inherits:** :ref:`VBoxContainer` **<** :ref:`BoxContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Editor dock for managing files in the project. +Godot editor's dock for managing files in the project. .. rst-class:: classref-introduction-group @@ -21,7 +21,7 @@ Description This class is available only in :ref:`EditorPlugin`\ s and can't be instantiated. You can access it using :ref:`EditorInterface.get_file_system_dock`. -While FileSystemDock doesn't expose any methods for file manipulation, you can listen for various file-related signals. +While **FileSystemDock** doesn't expose any methods for file manipulation, it can listen for various file-related signals. .. rst-class:: classref-reftable-group diff --git a/classes/class_float.rst b/classes/class_float.rst index d7e59a9a1f6..b8bc8076a98 100644 --- a/classes/class_float.rst +++ b/classes/class_float.rst @@ -10,18 +10,18 @@ float ===== -Float built-in type. +A built-in type for floating point numbers. .. rst-class:: classref-introduction-group Description ----------- -The **float** built-in type is a 64-bit double-precision floating-point number, equivalent to ``double`` in C++. This type has 14 reliable decimal digits of precision. The **float** type can be stored in :ref:`Variant`, which is the generic type used by the engine. The maximum value of **float** is approximately ``1.79769e308``, and the minimum is approximately ``-1.79769e308``. +The **float** built-in type is a 64-bit double-precision floating-point number, equivalent to ``double`` in C++. This type has 14 reliable decimal digits of precision. The maximum value of **float** is approximately ``1.79769e308``, and the minimum is approximately ``-1.79769e308``. Many methods and properties in the engine use 32-bit single-precision floating-point numbers instead, equivalent to ``float`` in C++, which have 6 reliable decimal digits of precision. For data structures such as :ref:`Vector2` and :ref:`Vector3`, Godot uses 32-bit floating-point numbers by default, but it can be changed to use 64-bit doubles if Godot is compiled with the ``precision=double`` option. -Math done using the **float** type is not guaranteed to be exact or deterministic, and will often result in small errors. You should usually use the :ref:`@GlobalScope.is_equal_approx` and :ref:`@GlobalScope.is_zero_approx` methods instead of ``==`` to compare **float** values for equality. +Math done using the **float** type is not guaranteed to be exact and will often result in small errors. You should usually use the :ref:`@GlobalScope.is_equal_approx` and :ref:`@GlobalScope.is_zero_approx` methods instead of ``==`` to compare **float** values for equality. .. rst-class:: classref-introduction-group @@ -200,6 +200,8 @@ Operator Descriptions Returns ``true`` if two floats are different from each other. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -222,7 +224,7 @@ Returns ``true`` if the integer has different value than the float. :ref:`Color` **operator *** **(** :ref:`Color` right **)** -Multiplies each component of the :ref:`Color` by the given **float**. +Multiplies each component of the :ref:`Color`, including the alpha, by the given **float**. :: @@ -468,6 +470,8 @@ Divides a **float** by an :ref:`int`. The result is a **float**. Returns ``true`` if the left float is less than the right one. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -492,6 +496,8 @@ Returns ``true`` if this **float** is less than the given :ref:`int`. Returns ``true`` if the left float is less than or equal to the right one. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -518,6 +524,8 @@ Returns ``true`` if both floats are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`@GlobalScope.is_equal_approx` or :ref:`@GlobalScope.is_zero_approx` instead, which are more reliable. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -542,6 +550,8 @@ Returns ``true`` if the **float** and the given :ref:`int` are equal. Returns ``true`` if the left float is greater than the right one. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -566,6 +576,8 @@ Returns ``true`` if this **float** is greater than the given :ref:`int` doesn't behave the same as other numbers. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_flowcontainer.rst b/classes/class_flowcontainer.rst index 943a33194e5..862e9d7b5d5 100644 --- a/classes/class_flowcontainer.rst +++ b/classes/class_flowcontainer.rst @@ -14,16 +14,21 @@ FlowContainer **Inherited By:** :ref:`HFlowContainer`, :ref:`VFlowContainer` -Base class for flow containers. +A container that arranges its child controls horizontally or vertically and wraps them around at the borders. .. rst-class:: classref-introduction-group Description ----------- -Arranges child :ref:`Control` nodes vertically or horizontally in a left-to-right or top-to-bottom flow. +A container that arranges its child controls horizontally or vertically and wraps them around at the borders. This is similar to how text in a book wraps around when no more words can fit on a line. -A line is filled with :ref:`Control` nodes until no more fit on the same line, similar to text in an autowrapped label. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_font.rst b/classes/class_font.rst index d53cd4edc8f..7cf794d10e1 100644 --- a/classes/class_font.rst +++ b/classes/class_font.rst @@ -14,14 +14,14 @@ Font **Inherited By:** :ref:`FontFile`, :ref:`FontVariation`, :ref:`SystemFont` -Base class for fonts and font variations. +Abstract base class for fonts and font variations. .. rst-class:: classref-introduction-group Description ----------- -Font is the abstract base class for font, so it shouldn't be used directly. Other types of fonts inherit from it. +Abstract base class for different font types. It has methods for drawing text and font character introspection. .. rst-class:: classref-reftable-group diff --git a/classes/class_fontfile.rst b/classes/class_fontfile.rst index 4a611a30b28..902e05dd6e1 100644 --- a/classes/class_fontfile.rst +++ b/classes/class_fontfile.rst @@ -12,7 +12,7 @@ FontFile **Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Font source data and prerendered glyph cache, imported from dynamic or bitmap font. +Holds font source data and prerendered glyph cache, imported from a dynamic or a bitmap font. .. rst-class:: classref-introduction-group @@ -35,9 +35,9 @@ Supported font formats: \ **Note:** A character is a symbol that represents an item (letter, digit etc.) in an abstract way. -\ **Note:** A glyph is a bitmap or shape used to draw one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source. +\ **Note:** A glyph is a bitmap or a shape used to draw one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source. -\ **Note:** If a none of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code. +\ **Note:** If none of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code. .. tabs:: diff --git a/classes/class_fontvariation.rst b/classes/class_fontvariation.rst index ed48d8300ad..3d5ba494c41 100644 --- a/classes/class_fontvariation.rst +++ b/classes/class_fontvariation.rst @@ -12,14 +12,14 @@ FontVariation **Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Variation of the :ref:`Font`. +A variation of a font with additional settings. .. rst-class:: classref-introduction-group Description ----------- -OpenType variations, simulated bold / slant, and additional font settings like OpenType features and extra spacing. +Provides OpenType variations, simulated bold / slant, and additional font settings like OpenType features and extra spacing. To use simulated bold font variant: diff --git a/classes/class_generic6dofjoint3d.rst b/classes/class_generic6dofjoint3d.rst index a154d1572a9..f00d0bbb4b8 100644 --- a/classes/class_generic6dofjoint3d.rst +++ b/classes/class_generic6dofjoint3d.rst @@ -12,14 +12,16 @@ Generic6DOFJoint3D **Inherits:** :ref:`Joint3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -The generic 6-degrees-of-freedom joint can implement a variety of joint types by locking certain axes' rotation or translation. +A physics joint that allows for complex movement and rotation between two 3D physics bodies. .. rst-class:: classref-introduction-group Description ----------- -The first 3 DOF axes are linear axes, which represent translation of Bodies, and the latter 3 DOF axes represent the angular motion. Each axis can be either locked, or limited. +The **Generic6DOFJoint3D** (6 Degrees Of Freedom) joint allows for implementing custom types of joints by locking the rotation and translation of certain axes. + +The first 3 DOF represent the linear motion of the physics bodies and the last 3 DOF represent the angular motion of the physics bodies. Each axis can be either locked, or limited. .. rst-class:: classref-reftable-group diff --git a/classes/class_geometry2d.rst b/classes/class_geometry2d.rst index f97703f6049..168c23f0481 100644 --- a/classes/class_geometry2d.rst +++ b/classes/class_geometry2d.rst @@ -12,14 +12,14 @@ Geometry2D **Inherits:** :ref:`Object` -Helper node to calculate generic geometry operations in 2D space. +Provides methods for some common 2D geometric operations. .. rst-class:: classref-introduction-group Description ----------- -Geometry2D provides users with a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations. +Provides a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations in 2D. .. rst-class:: classref-reftable-group diff --git a/classes/class_geometry3d.rst b/classes/class_geometry3d.rst index 1f866f21cd1..af0b8a0352a 100644 --- a/classes/class_geometry3d.rst +++ b/classes/class_geometry3d.rst @@ -12,14 +12,14 @@ Geometry3D **Inherits:** :ref:`Object` -Helper node to calculate generic geometry operations in 3D space. +Provides methods for some common 3D geometric operations. .. rst-class:: classref-introduction-group Description ----------- -Geometry3D provides users with a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations. +Provides a set of helper functions to create geometric shapes, compute intersections between shapes, and process various other geometric operations in 3D. .. rst-class:: classref-reftable-group diff --git a/classes/class_gltfstate.rst b/classes/class_gltfstate.rst index 42f885fb904..f190555ff6c 100644 --- a/classes/class_gltfstate.rst +++ b/classes/class_gltfstate.rst @@ -88,6 +88,8 @@ Methods +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`GLTFMesh[]` | :ref:`get_meshes` **(** **)** | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_node_index` **(** :ref:`Node` scene_node **)** | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`GLTFNode[]` | :ref:`get_nodes` **(** **)** | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Node` | :ref:`get_scene_node` **(** :ref:`int` idx **)** | @@ -546,6 +548,20 @@ Returns an array of all :ref:`GLTFMesh`\ es in the GLTF file. Th ---- +.. _class_GLTFState_method_get_node_index: + +.. rst-class:: classref-method + +:ref:`int` **get_node_index** **(** :ref:`Node` scene_node **)** + +Returns the index of the :ref:`GLTFNode` corresponding to this Godot scene node. This is the inverse of :ref:`get_scene_node`. Useful during the export process. + +\ **Note:** Not every Godot scene node will have a corresponding :ref:`GLTFNode`, and not every :ref:`GLTFNode` will have a scene node generated. If there is no :ref:`GLTFNode` index for this scene node, ``-1`` is returned. + +.. rst-class:: classref-item-separator + +---- + .. _class_GLTFState_method_get_nodes: .. rst-class:: classref-method @@ -564,7 +580,9 @@ Returns an array of all :ref:`GLTFNode`\ s in the GLTF file. The :ref:`Node` **get_scene_node** **(** :ref:`int` idx **)** -Returns the Godot scene node that corresponds to the same index as the :ref:`GLTFNode` it was generated from. Not every :ref:`GLTFNode` will have a scene node generated, and not every generated scene node will have a corresponding :ref:`GLTFNode`. +Returns the Godot scene node that corresponds to the same index as the :ref:`GLTFNode` it was generated from. This is the inverse of :ref:`get_node_index`. Useful during the import process. + +\ **Note:** Not every :ref:`GLTFNode` will have a scene node generated, and not every generated scene node will have a corresponding :ref:`GLTFNode`. If there is no scene node for this :ref:`GLTFNode` index, ``null`` is returned. .. rst-class:: classref-item-separator diff --git a/classes/class_gradient.rst b/classes/class_gradient.rst index 577b425424e..8fdeb2b646e 100644 --- a/classes/class_gradient.rst +++ b/classes/class_gradient.rst @@ -31,13 +31,15 @@ Properties .. table:: :widths: auto - +-----------------------------------------------------------+-----------------------------------------------------------------------+----------------------------------------------+ - | :ref:`PackedColorArray` | :ref:`colors` | ``PackedColorArray(0, 0, 0, 1, 1, 1, 1, 1)`` | - +-----------------------------------------------------------+-----------------------------------------------------------------------+----------------------------------------------+ - | :ref:`InterpolationMode` | :ref:`interpolation_mode` | ``0`` | - +-----------------------------------------------------------+-----------------------------------------------------------------------+----------------------------------------------+ - | :ref:`PackedFloat32Array` | :ref:`offsets` | ``PackedFloat32Array(0, 1)`` | - +-----------------------------------------------------------+-----------------------------------------------------------------------+----------------------------------------------+ + +-----------------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------+ + | :ref:`PackedColorArray` | :ref:`colors` | ``PackedColorArray(0, 0, 0, 1, 1, 1, 1, 1)`` | + +-----------------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------+ + | :ref:`ColorSpace` | :ref:`interpolation_color_space` | ``0`` | + +-----------------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------+ + | :ref:`InterpolationMode` | :ref:`interpolation_mode` | ``0`` | + +-----------------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------+ + | :ref:`PackedFloat32Array` | :ref:`offsets` | ``PackedFloat32Array(0, 1)`` | + +-----------------------------------------------------------+-------------------------------------------------------------------------------------+----------------------------------------------+ .. rst-class:: classref-reftable-group @@ -106,6 +108,40 @@ Constant interpolation, color changes abruptly at each point and stays uniform b Cubic interpolation. +.. rst-class:: classref-item-separator + +---- + +.. _enum_Gradient_ColorSpace: + +.. rst-class:: classref-enumeration + +enum **ColorSpace**: + +.. _class_Gradient_constant_GRADIENT_COLOR_SPACE_SRGB: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorSpace` **GRADIENT_COLOR_SPACE_SRGB** = ``0`` + +sRGB color space. + +.. _class_Gradient_constant_GRADIENT_COLOR_SPACE_LINEAR_SRGB: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorSpace` **GRADIENT_COLOR_SPACE_LINEAR_SRGB** = ``1`` + +Linear sRGB color space. + +.. _class_Gradient_constant_GRADIENT_COLOR_SPACE_OKLAB: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorSpace` **GRADIENT_COLOR_SPACE_OKLAB** = ``2`` + +`Oklab `__ color space. This color space provides a smooth and uniform-looking transition between colors. + .. rst-class:: classref-section-separator ---- @@ -132,6 +168,25 @@ Gradient's colors returned as a :ref:`PackedColorArray`. ---- +.. _class_Gradient_property_interpolation_color_space: + +.. rst-class:: classref-property + +:ref:`ColorSpace` **interpolation_color_space** = ``0`` + +.. rst-class:: classref-property-setget + +- void **set_interpolation_color_space** **(** :ref:`ColorSpace` value **)** +- :ref:`ColorSpace` **get_interpolation_color_space** **(** **)** + +The color space used to interpolate between points of the gradient. It does not affect the returned colors, which will always be in sRGB space. See :ref:`ColorSpace` for available modes. + +\ **Note:** This setting has no effect when :ref:`interpolation_mode` is set to :ref:`GRADIENT_INTERPOLATE_CONSTANT`. + +.. rst-class:: classref-item-separator + +---- + .. _class_Gradient_property_interpolation_mode: .. rst-class:: classref-property @@ -143,7 +198,7 @@ Gradient's colors returned as a :ref:`PackedColorArray`. - void **set_interpolation_mode** **(** :ref:`InterpolationMode` value **)** - :ref:`InterpolationMode` **get_interpolation_mode** **(** **)** -Defines how the colors between points of the gradient are interpolated. See :ref:`InterpolationMode` for available modes. +The algorithm used to interpolate between points of the gradient. See :ref:`InterpolationMode` for available modes. .. rst-class:: classref-item-separator diff --git a/classes/class_gradienttexture2d.rst b/classes/class_gradienttexture2d.rst index d9913c3af51..11f191c422e 100644 --- a/classes/class_gradienttexture2d.rst +++ b/classes/class_gradienttexture2d.rst @@ -80,6 +80,14 @@ The colors are linearly interpolated in a straight line. The colors are linearly interpolated in a circular pattern. +.. _class_GradientTexture2D_constant_FILL_SQUARE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Fill` **FILL_SQUARE** = ``2`` + +The colors are linearly interpolated in a square pattern. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_graphedit.rst b/classes/class_graphedit.rst index 752fb56f360..37b1e1207a9 100644 --- a/classes/class_graphedit.rst +++ b/classes/class_graphedit.rst @@ -12,18 +12,16 @@ GraphEdit **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -GraphEdit is a control responsible for displaying and manipulating graph-like data using :ref:`GraphNode`\ s. It provides access to creation, removal, connection, and disconnection of nodes. +An editor for graph-like structures, using :ref:`GraphNode`\ s. .. rst-class:: classref-introduction-group Description ----------- -**Note:** Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. +**GraphEdit** provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. -GraphEdit provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. - -GraphEdit by itself is only an empty container, representing an infinite grid where :ref:`GraphNode`\ s can be placed. Each :ref:`GraphNode` represent a node in the graph, a single unit of data in the connected scheme. GraphEdit, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or close a :ref:`GraphNode`, a signal is emitted in the GraphEdit, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. +\ **GraphEdit** by itself is only an empty container, representing an infinite grid where :ref:`GraphNode`\ s can be placed. Each :ref:`GraphNode` represents a node in the graph, a single unit of data in the connected scheme. **GraphEdit**, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or close a :ref:`GraphNode`, a signal is emitted in the **GraphEdit**, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. \ **Performance:** It is greatly advised to enable low-processor usage mode (see :ref:`OS.low_processor_usage_mode`) when using GraphEdits. diff --git a/classes/class_graphnode.rst b/classes/class_graphnode.rst index 40e5af47b9c..11bba183c16 100644 --- a/classes/class_graphnode.rst +++ b/classes/class_graphnode.rst @@ -12,22 +12,20 @@ GraphNode **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -GraphNode is a :ref:`Container` control that represents a single data unit in a :ref:`GraphEdit` graph. You can customize the number, type, and color of left- and right-side connection ports. +A container with connection ports, representing a node in a :ref:`GraphEdit`. .. rst-class:: classref-introduction-group Description ----------- -**Note:** Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. +**GraphNode** allows to create nodes for a :ref:`GraphEdit` graph with customizable content based on its child controls. **GraphNode** is derived from :ref:`Container` and it is responsible for placing its children on screen. This works similar to :ref:`VBoxContainer`. Children, in turn, provide **GraphNode** with so-called slots, each of which can have a connection port on either side. -GraphNode allows to create nodes for a :ref:`GraphEdit` graph with customizable content based on its child :ref:`Control`\ s. GraphNode is a :ref:`Container` and is responsible for placing its children on screen. This works similar to :ref:`VBoxContainer`. Children, in turn, provide GraphNode with so-called slots, each of which can have a connection port on either side. This is similar to how :ref:`TabContainer` uses children to create the tabs. - -Each GraphNode slot is defined by its index and can provide the node with up to two ports: one on the left, and one on the right. By convention the left port is also referred to as the input port and the right port is referred to as the output port. Each port can be enabled and configured individually, using different type and color. The type is an arbitrary value that you can define using your own considerations. The parent :ref:`GraphEdit` will receive this information on each connect and disconnect request. +Each **GraphNode** slot is defined by its index and can provide the node with up to two ports: one on the left, and one on the right. By convention the left port is also referred to as the **input port** and the right port is referred to as the **output port**. Each port can be enabled and configured individually, using different type and color. The type is an arbitrary value that you can define using your own considerations. The parent :ref:`GraphEdit` will receive this information on each connect and disconnect request. Slots can be configured in the Inspector dock once you add at least one child :ref:`Control`. The properties are grouped by each slot's index in the "Slot" section. -\ **Note:** While GraphNode is set up using slots and slot indices, connections are made between the ports which are enabled. Because of that :ref:`GraphEdit` uses port's index and not slot's index. You can use :ref:`get_connection_input_slot` and :ref:`get_connection_output_slot` to get the slot index from the port index. +\ **Note:** While GraphNode is set up using slots and slot indices, connections are made between the ports which are enabled. Because of that, :ref:`GraphEdit` uses the port's index and not the slot's index. You can use :ref:`get_connection_input_slot` and :ref:`get_connection_output_slot` to get the slot index from the port index. .. rst-class:: classref-reftable-group diff --git a/classes/class_gridcontainer.rst b/classes/class_gridcontainer.rst index 00019f4451c..09701b1b18d 100644 --- a/classes/class_gridcontainer.rst +++ b/classes/class_gridcontainer.rst @@ -12,25 +12,23 @@ GridContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Grid container used to arrange Control-derived children in a grid like layout. +A container that arranges its child controls in a grid layout. .. rst-class:: classref-introduction-group Description ----------- -GridContainer will arrange its Control-derived children in a grid like structure, the grid columns are specified using the :ref:`columns` property and the number of rows will be equal to the number of children in the container divided by the number of columns. For example, if the container has 5 children, and 2 columns, there will be 3 rows in the container. +**GridContainer** arranges its child controls in a grid layout. The number of columns is specified by the :ref:`columns` property, whereas the number of rows depends on how many are needed for the child controls. The number of rows and columns is preserved for every size of the container. -Notice that grid layout will preserve the columns and rows for every size of the container, and that empty columns will be expanded automatically. - -\ **Note:** GridContainer only works with child nodes inheriting from Control. It won't rearrange child nodes inheriting from Node2D. +\ **Note:** **GridContainer** only works with child nodes inheriting from :ref:`Control`. It won't rearrange child nodes inheriting from :ref:`Node2D`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` - `OS Test Demo `__ diff --git a/classes/class_groovejoint2d.rst b/classes/class_groovejoint2d.rst index f150e0a0a76..770d6c199ab 100644 --- a/classes/class_groovejoint2d.rst +++ b/classes/class_groovejoint2d.rst @@ -12,14 +12,14 @@ GrooveJoint2D **Inherits:** :ref:`Joint2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Groove constraint for 2D physics. +A physics joint that restricts the movement of two 2D physics bodies to a fixed axis. .. rst-class:: classref-introduction-group Description ----------- -Groove constraint for 2D physics. This is useful for making a body "slide" through a segment placed in another. +A physics joint that restricts the movement of two 2D physics bodies to a fixed axis. For example, a :ref:`StaticBody2D` representing a piston base can be attached to a :ref:`RigidBody2D` representing the piston head, moving up and down. .. rst-class:: classref-reftable-group diff --git a/classes/class_hashingcontext.rst b/classes/class_hashingcontext.rst index 0f8934568ba..879d0ad0722 100644 --- a/classes/class_hashingcontext.rst +++ b/classes/class_hashingcontext.rst @@ -12,14 +12,14 @@ HashingContext **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Context to compute cryptographic hashes over multiple iterations. +Provides functionality for computing cryptographic hashes chunk by chunk. .. rst-class:: classref-introduction-group Description ----------- -The HashingContext class provides an interface for computing cryptographic hashes over multiple iterations. This is useful for example when computing hashes of big files (so you don't have to load them all in memory), network streams, and data streams in general (so you don't have to hold buffers). +The HashingContext class provides an interface for computing cryptographic hashes over multiple iterations. Useful for computing hashes of big files (so you don't have to load them all in memory), network streams, and data streams in general (so you don't have to hold buffers). The :ref:`HashType` enum shows the supported hashing algorithms. diff --git a/classes/class_hboxcontainer.rst b/classes/class_hboxcontainer.rst index 33859f18cbb..d304213d540 100644 --- a/classes/class_hboxcontainer.rst +++ b/classes/class_hboxcontainer.rst @@ -14,21 +14,21 @@ HBoxContainer **Inherited By:** :ref:`EditorResourcePicker` -Horizontal box container. +A container that arranges its child controls horizontally. .. rst-class:: classref-introduction-group Description ----------- -Horizontal box container. See :ref:`BoxContainer`. +A variant of :ref:`BoxContainer` that can only arrange its child controls horizontally. Child controls are rearranged automatically when their minimum size changes. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_heightmapshape3d.rst b/classes/class_heightmapshape3d.rst index 46f8074b964..8603b283b1f 100644 --- a/classes/class_heightmapshape3d.rst +++ b/classes/class_heightmapshape3d.rst @@ -12,16 +12,16 @@ HeightMapShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Height map shape resource for 3D physics. +A 3D height map shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -Height map shape resource, which can be added to a :ref:`PhysicsBody3D` or :ref:`Area3D`. Heightmap collision is typically used for colliding with terrains. However, since heightmaps cannot store overhangs, collisions with other structures (such as buildings) must be done with other collision shapes such as :ref:`ConcavePolygonShape3D`. If needed, "holes" can be created in an **HeightMapShape3D** by assigning very low points (like ``-100000``) in the desired area. +A 3D heightmap shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. This is useful for terrain, but it is limited as overhangs (such as caves) cannot be stored. Holes in a **HeightMapShape3D** are created by assigning very low values to points in the desired area. -\ **Performance:** **HeightMapShape3D** is faster to check collisions against compared to :ref:`ConcavePolygonShape3D`, but it is slower than primitive collision shapes such as :ref:`SphereShape3D` or :ref:`BoxShape3D`. +\ **Performance:** **HeightMapShape3D** is faster to check collisions against than :ref:`ConcavePolygonShape3D`, but it is significantly slower than primitive shapes like :ref:`BoxShape3D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_hflowcontainer.rst b/classes/class_hflowcontainer.rst index 580a1fe892c..00ab895c355 100644 --- a/classes/class_hflowcontainer.rst +++ b/classes/class_hflowcontainer.rst @@ -12,14 +12,21 @@ HFlowContainer **Inherits:** :ref:`FlowContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal flow container. +A container that arranges its child controls horizontally and wraps them around at the borders. .. rst-class:: classref-introduction-group Description ----------- -Horizontal version of :ref:`FlowContainer`. +A variant of :ref:`FlowContainer` that can only arrange its child controls horizontally, wrapping them around at the borders. This is similar to how text in a book wraps around when no more words can fit on a line. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_hingejoint3d.rst b/classes/class_hingejoint3d.rst index 1c852c33770..47e56490aff 100644 --- a/classes/class_hingejoint3d.rst +++ b/classes/class_hingejoint3d.rst @@ -12,14 +12,14 @@ HingeJoint3D **Inherits:** :ref:`Joint3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -A hinge between two 3D PhysicsBodies. +A physics joint that restricts the rotation of a 3D physics body around an axis relative to another physics body. .. rst-class:: classref-introduction-group Description ----------- -A HingeJoint3D normally uses the Z axis of body A as the hinge axis, another axis can be specified when adding it manually though. See also :ref:`Generic6DOFJoint3D`. +A physics joint that restricts the rotation of a 3D physics body around an axis relative to another physics body. For example, Body A can be a :ref:`StaticBody3D` representing a door hinge that a :ref:`RigidBody3D` rotates around. .. rst-class:: classref-reftable-group diff --git a/classes/class_hscrollbar.rst b/classes/class_hscrollbar.rst index fc55875a1f1..6017dd3c86c 100644 --- a/classes/class_hscrollbar.rst +++ b/classes/class_hscrollbar.rst @@ -12,14 +12,14 @@ HScrollBar **Inherits:** :ref:`ScrollBar` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal scroll bar. +A horizontal scrollbar that goes from left (min) to right (max). .. rst-class:: classref-introduction-group Description ----------- -Horizontal version of :ref:`ScrollBar`, which goes from left (min) to right (max). +A horizontal scrollbar, typically used to navigate through content that extends beyond the visible width of a control. It is a :ref:`Range`-based control and goes from left (min) to right (max). .. rst-class:: classref-reftable-group diff --git a/classes/class_hseparator.rst b/classes/class_hseparator.rst index 06f01ed7ec1..150e0f99fb7 100644 --- a/classes/class_hseparator.rst +++ b/classes/class_hseparator.rst @@ -12,14 +12,14 @@ HSeparator **Inherits:** :ref:`Separator` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal separator. +A horizontal line used for separating other controls. .. rst-class:: classref-introduction-group Description ----------- -Horizontal separator. See :ref:`Separator`. Even though it looks horizontal, it is used to separate objects vertically. +A horizontal separator used for separating other controls that are arranged **vertically**. **HSeparator** is purely visual and normally drawn as a :ref:`StyleBoxLine`. .. rst-class:: classref-reftable-group diff --git a/classes/class_hslider.rst b/classes/class_hslider.rst index b83747fc75e..800f756f39d 100644 --- a/classes/class_hslider.rst +++ b/classes/class_hslider.rst @@ -12,16 +12,14 @@ HSlider **Inherits:** :ref:`Slider` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal slider. +A horizontal slider that goes from left (min) to right (max). .. rst-class:: classref-introduction-group Description ----------- -Horizontal slider. See :ref:`Slider`. This one goes from left (min) to right (max). - -\ **Note:** The :ref:`Range.changed` and :ref:`Range.value_changed` signals are part of the :ref:`Range` class which this class inherits from. +A horizontal slider, used to adjust a value by moving a grabber along a horizontal axis. It is a :ref:`Range`-based control and goes from left (min) to right (max). .. rst-class:: classref-reftable-group diff --git a/classes/class_hsplitcontainer.rst b/classes/class_hsplitcontainer.rst index 0f1dc3bd827..334c110e602 100644 --- a/classes/class_hsplitcontainer.rst +++ b/classes/class_hsplitcontainer.rst @@ -12,21 +12,21 @@ HSplitContainer **Inherits:** :ref:`SplitContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Horizontal split container. +A container that splits two child controls horizontally and provides a grabber for adjusting the split ratio. .. rst-class:: classref-introduction-group Description ----------- -Horizontal split container. See :ref:`SplitContainer`. This goes from left to right. +A container that accepts only two child controls, then arranges them horizontally and creates a divisor between them. The divisor can be dragged around to change the size relation between the child controls. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_httpclient.rst b/classes/class_httpclient.rst index 55bac119dce..3ad584fed49 100644 --- a/classes/class_httpclient.rst +++ b/classes/class_httpclient.rst @@ -27,7 +27,7 @@ See the :ref:`HTTPRequest` node for a higher-level alternativ A **HTTPClient** should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports Transport Layer Security (TLS), including server certificate verification. HTTP status codes in the 2xx range indicate success, 3xx redirection (i.e. "try again, but over here"), 4xx something was wrong with the request, and 5xx something went wrong on the server's side. -For more information on HTTP, see https://developer.mozilla.org/en-US/docs/Web/HTTP (or read RFC 2616 to get it straight from the source: https://tools.ietf.org/html/rfc2616). +For more information on HTTP, see `MDN's documentation on HTTP `__ (or read `RFC 2616 `__ to get it straight from the source). \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. diff --git a/classes/class_httprequest.rst b/classes/class_httprequest.rst index 4972f8174e3..94172fe96f7 100644 --- a/classes/class_httprequest.rst +++ b/classes/class_httprequest.rst @@ -49,7 +49,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content # Note: Don't make simultaneous requests using a single HTTPRequest node. # The snippet below is provided for reference only. var body = JSON.new().stringify({"name": "Godette"}) - error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body) + error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body) if error != OK: push_error("An error occurred in the HTTP request.") @@ -85,7 +85,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content { { "name", "Godette" } }); - error = httpRequest.Request("https://httpbin.org/post", null, true, HTTPClient.Method.Post, body); + error = httpRequest.Request("https://httpbin.org/post", null, HTTPClient.Method.Post, body); if (error != Error.Ok) { GD.PushError("An error occurred in the HTTP request."); @@ -386,7 +386,7 @@ Request reached its maximum redirect limit, see :ref:`max_redirects` **RESULT_TIMEOUT** = ``13`` - +Request failed due to a timeout. If you expect requests to take a long time, try increasing the value of :ref:`timeout` or setting it to ``0.0`` to remove the timeout completely. .. rst-class:: classref-section-separator @@ -501,7 +501,7 @@ Maximum number of allowed redirects. - void **set_timeout** **(** :ref:`float` value **)** - :ref:`float` **get_timeout** **(** **)** -If set to a value greater than ``0.0`` before the request starts, the HTTP request will time out after ``timeout`` seconds have passed and the request is not *completed* yet. For small HTTP requests such as REST API usage, set :ref:`timeout` to a value between ``10.0`` and ``30.0`` to prevent the application from getting stuck if the request fails to get a response in a timely manner. For file downloads, leave this to ``0.0`` to prevent the download from failing if it takes too much time. +The duration to wait in seconds before a request times out. If :ref:`timeout` is set to ``0.0`` then the request will never time out. For simple requests, such as communication with a REST API, it is recommended that :ref:`timeout` is set to a value suitable for the server response time (e.g. between ``1.0`` and ``10.0``). This will help prevent unwanted timeouts caused by variation in server response times while still allowing the application to detect when a request has timed out. For larger requests such as file downloads it is suggested the :ref:`timeout` be set to ``0.0``, disabling the timeout functionality. This will help to prevent large transfers from failing due to exceeding the timeout value. .. rst-class:: classref-item-separator diff --git a/classes/class_input.rst b/classes/class_input.rst index 07051b63de6..e7adb7b5733 100644 --- a/classes/class_input.rst +++ b/classes/class_input.rst @@ -12,16 +12,16 @@ Input **Inherits:** :ref:`Object` -A singleton that deals with inputs. +A singleton for handling inputs. .. rst-class:: classref-introduction-group Description ----------- -A singleton that deals with inputs. This includes key presses, mouse buttons and movement, joypads, and input actions. Actions and their events can be set in the **Input Map** tab in the **Project > Project Settings**, or with the :ref:`InputMap` class. +The **Input** singleton handles key presses, mouse buttons and movement, gamepads, and input actions. Actions and their events can be set in the **Input Map** tab in **Project > Project Settings**, or with the :ref:`InputMap` class. -\ **Note:** The methods here reflect the global input state and are not affected by :ref:`Control.accept_event` or :ref:`Viewport.set_input_as_handled`, which only deal with the way input is propagated in the :ref:`SceneTree`. +\ **Note:** **Input**'s methods reflect the global input state and are not affected by :ref:`Control.accept_event` or :ref:`Viewport.set_input_as_handled`, as those methods only deal with the way input is propagated in the :ref:`SceneTree`. .. rst-class:: classref-introduction-group @@ -600,7 +600,7 @@ Returns the current value of the joypad axis at given index (see :ref:`JoyAxis` **get_joy_guid** **(** :ref:`int` device **)** |const| -Returns a SDL2-compatible device GUID on platforms that use gamepad remapping. Returns ``"Default Gamepad"`` otherwise. +Returns a SDL2-compatible device GUID on platforms that use gamepad remapping, e.g. ``030000004c050000c405000000010000``. Returns ``"Default Gamepad"`` otherwise. Godot uses the `SDL2 game controller database `__ to determine gamepad names and mappings based on this GUID. .. rst-class:: classref-item-separator @@ -612,7 +612,7 @@ Returns a SDL2-compatible device GUID on platforms that use gamepad remapping. R :ref:`String` **get_joy_name** **(** :ref:`int` device **)** -Returns the name of the joypad at the specified device index. +Returns the name of the joypad at the specified device index, e.g. ``PS4 Controller``. Godot uses the `SDL2 game controller database `__ to determine gamepad names. .. rst-class:: classref-item-separator diff --git a/classes/class_inputevent.rst b/classes/class_inputevent.rst index 826051533d1..cf935daba16 100644 --- a/classes/class_inputevent.rst +++ b/classes/class_inputevent.rst @@ -14,21 +14,21 @@ InputEvent **Inherited By:** :ref:`InputEventAction`, :ref:`InputEventFromWindow`, :ref:`InputEventJoypadButton`, :ref:`InputEventJoypadMotion`, :ref:`InputEventMIDI`, :ref:`InputEventShortcut` -Generic input event. +Abstract base class for input events. .. rst-class:: classref-introduction-group Description ----------- -Base class of all sort of input event. See :ref:`Node._input`. +Abstract base class of all types of input events. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` - :doc:`Viewport and canvas transforms <../tutorials/2d/2d_transforms>` diff --git a/classes/class_inputeventaction.rst b/classes/class_inputeventaction.rst index 840586210db..c5bf81377eb 100644 --- a/classes/class_inputeventaction.rst +++ b/classes/class_inputeventaction.rst @@ -12,14 +12,14 @@ InputEventAction **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for actions. +An input event type for actions. .. rst-class:: classref-introduction-group Description ----------- -Contains a generic action which can be targeted from several types of inputs. Actions can be created from the **Input Map** tab in the **Project > Project Settings** menu. See :ref:`Node._input`. +Contains a generic action which can be targeted from several types of inputs. Actions and their events can be set in the **Input Map** tab in **Project > Project Settings**, or with the :ref:`InputMap` class. \ **Note:** Unlike the other :ref:`InputEvent` subclasses which map to unique physical events, this virtual one is not emitted by the engine. This class is useful to emit actions manually with :ref:`Input.parse_input_event`, which are then received in :ref:`Node._input`. To check if a physical event matches an action from the Input Map, use :ref:`InputEvent.is_action` and :ref:`InputEvent.is_action_pressed`. @@ -28,7 +28,7 @@ Contains a generic action which can be targeted from several types of inputs. Ac Tutorials --------- -- `InputEvent: Actions <../tutorials/inputs/inputevent.html#actions>`__ +- `Using InputEvent: Actions <../tutorials/inputs/inputevent.html#actions>`__ - `2D Dodge The Creeps Demo `__ diff --git a/classes/class_inputeventfromwindow.rst b/classes/class_inputeventfromwindow.rst index 7065219ff08..a4d52d695bb 100644 --- a/classes/class_inputeventfromwindow.rst +++ b/classes/class_inputeventfromwindow.rst @@ -14,7 +14,7 @@ InputEventFromWindow **Inherited By:** :ref:`InputEventScreenDrag`, :ref:`InputEventScreenTouch`, :ref:`InputEventWithModifiers` -Base class for :ref:`Viewport`-based input events. +Abstract base class for :ref:`Viewport`-based input events. .. rst-class:: classref-introduction-group diff --git a/classes/class_inputeventgesture.rst b/classes/class_inputeventgesture.rst index ceb0aa276e5..111e1f7fe2d 100644 --- a/classes/class_inputeventgesture.rst +++ b/classes/class_inputeventgesture.rst @@ -14,14 +14,21 @@ InputEventGesture **Inherited By:** :ref:`InputEventMagnifyGesture`, :ref:`InputEventPanGesture` -Base class for touch control gestures. +Abstract base class for touch gestures. .. rst-class:: classref-introduction-group Description ----------- -InputEventGesture is sent when a user performs a supported gesture on a touch screen. Gestures can't be emulated using mouse, because they typically require multi-touch. +InputEventGestures are sent when a user performs a supported gesture on a touch screen. Gestures can't be emulated using mouse, because they typically require multi-touch. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventjoypadbutton.rst b/classes/class_inputeventjoypadbutton.rst index 18cfadc24a9..ab5300b2e52 100644 --- a/classes/class_inputeventjoypadbutton.rst +++ b/classes/class_inputeventjoypadbutton.rst @@ -12,7 +12,7 @@ InputEventJoypadButton **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event for gamepad buttons. +Represents a gamepad button being pressed or released. .. rst-class:: classref-introduction-group @@ -26,7 +26,7 @@ Input event type for gamepad buttons. For gamepad analog sticks and joysticks, s Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventjoypadmotion.rst b/classes/class_inputeventjoypadmotion.rst index 129a0303f3f..6ef2c21a6fd 100644 --- a/classes/class_inputeventjoypadmotion.rst +++ b/classes/class_inputeventjoypadmotion.rst @@ -12,21 +12,21 @@ InputEventJoypadMotion **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for gamepad joysticks and other motions. For buttons, see ``InputEventJoypadButton``. +Represents axis motions (such as joystick or analog triggers) from a gamepad. .. rst-class:: classref-introduction-group Description ----------- -Stores information about joystick motions. One **InputEventJoypadMotion** represents one axis at a time. +Stores information about joystick motions. One **InputEventJoypadMotion** represents one axis at a time. For gamepad buttons, see :ref:`InputEventJoypadButton`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventkey.rst b/classes/class_inputeventkey.rst index 988b208deae..e2b2c46dc7b 100644 --- a/classes/class_inputeventkey.rst +++ b/classes/class_inputeventkey.rst @@ -12,25 +12,25 @@ InputEventKey **Inherits:** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for keyboard events. +Represents a key on a keyboard being pressed or released. .. rst-class:: classref-introduction-group Description ----------- -Stores key presses on the keyboard. Supports key presses, key releases and :ref:`echo` events. +An input event for keys on a keyboard. Supports key presses, key releases and :ref:`echo` events. It can also be received in :ref:`Node._unhandled_key_input`. \ **Note:** Events received from the keyboard usually have all properties set. Event mappings should have only one of the :ref:`keycode`, :ref:`physical_keycode` or :ref:`unicode` set. -When events are compared, properties are checked in the following priority - :ref:`keycode`, :ref:`physical_keycode` and :ref:`unicode`, events with the first matching value will be considered equal. +When events are compared, properties are checked in the following priority - :ref:`keycode`, :ref:`physical_keycode` and :ref:`unicode`. Events with the first matching value will be considered equal. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventmagnifygesture.rst b/classes/class_inputeventmagnifygesture.rst index cb93e7ae582..7f3f2659d4c 100644 --- a/classes/class_inputeventmagnifygesture.rst +++ b/classes/class_inputeventmagnifygesture.rst @@ -12,14 +12,21 @@ InputEventMagnifyGesture **Inherits:** :ref:`InputEventGesture` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`InputEvent` that represents a magnifying touch gesture. +Represents a magnifying touch gesture. .. rst-class:: classref-introduction-group Description ----------- -Magnify gesture is performed when the user pinches the touch screen. It's typically used for zooming. +Stores the factor of a magnifying touch gesture. This is usually performed when the user pinches the touch screen and used for zooming in/out. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group @@ -53,7 +60,7 @@ Property Descriptions - void **set_factor** **(** :ref:`float` value **)** - :ref:`float` **get_factor** **(** **)** -The amount (or delta) of the event. This value is higher the faster the gesture is performed. +The amount (or delta) of the event. This value is closer to ``1.0`` the slower the gesture is performed. .. |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_inputeventmidi.rst b/classes/class_inputeventmidi.rst index 468d535484d..02c671c28ce 100644 --- a/classes/class_inputeventmidi.rst +++ b/classes/class_inputeventmidi.rst @@ -12,14 +12,14 @@ InputEventMIDI **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event for MIDI inputs. +Represents an input event from a MIDI device, such as a piano. .. rst-class:: classref-introduction-group Description ----------- -InputEventMIDI allows receiving input events from MIDI devices such as a piano. MIDI stands for Musical Instrument Digital Interface. +InputEventMIDI allows receiving input events from MIDI (Musical Instrument Digital Interface) devices such as a piano. MIDI signals can be sent over a 5-pin MIDI connector or over USB, if your device supports both be sure to check the settings in the device to see which output it's using. diff --git a/classes/class_inputeventmouse.rst b/classes/class_inputeventmouse.rst index a9f62fed2a9..cfe1e28cc9e 100644 --- a/classes/class_inputeventmouse.rst +++ b/classes/class_inputeventmouse.rst @@ -21,14 +21,14 @@ Base input event type for mouse events. Description ----------- -Stores general mouse events information. +Stores general information about mouse events. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventmousebutton.rst b/classes/class_inputeventmousebutton.rst index ac70e894399..ddd0465e8af 100644 --- a/classes/class_inputeventmousebutton.rst +++ b/classes/class_inputeventmousebutton.rst @@ -12,20 +12,22 @@ InputEventMouseButton **Inherits:** :ref:`InputEventMouse` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for mouse button events. +Represents a mouse button being pressed or released. .. rst-class:: classref-introduction-group Description ----------- -Contains mouse click information. See :ref:`Node._input`. +Stores information about mouse click events. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` + - :doc:`Mouse and input coordinates <../tutorials/inputs/mouse_and_input_coordinates>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventmousemotion.rst b/classes/class_inputeventmousemotion.rst index 2c7aad2c565..fc84c79fd7a 100644 --- a/classes/class_inputeventmousemotion.rst +++ b/classes/class_inputeventmousemotion.rst @@ -12,14 +12,14 @@ InputEventMouseMotion **Inherits:** :ref:`InputEventMouse` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for mouse motion events. +Represents a mouse or a pen movement. .. rst-class:: classref-introduction-group Description ----------- -Contains mouse and pen motion information. Supports relative, absolute positions and velocity. See :ref:`Node._input`. +Stores information about a mouse or a pen motion. This includes relative position, absolute position, and velocity. See :ref:`Node._input`. \ **Note:** By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, set :ref:`Input.use_accumulated_input` to ``false`` to make events emitted as often as possible. If you use InputEventMouseMotion to draw lines, consider implementing `Bresenham's line algorithm `__ as well to avoid visible gaps in lines if the user is moving the mouse quickly. @@ -28,6 +28,8 @@ Contains mouse and pen motion information. Supports relative, absolute positions Tutorials --------- +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` + - :doc:`Mouse and input coordinates <../tutorials/inputs/mouse_and_input_coordinates>` - `3D Voxel Demo `__ diff --git a/classes/class_inputeventpangesture.rst b/classes/class_inputeventpangesture.rst index 1c58524a15b..9c1ade7e2e2 100644 --- a/classes/class_inputeventpangesture.rst +++ b/classes/class_inputeventpangesture.rst @@ -12,14 +12,21 @@ InputEventPanGesture **Inherits:** :ref:`InputEventGesture` **<** :ref:`InputEventWithModifiers` **<** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`InputEvent` that represents a panning touch gesture. +Represents a panning touch gesture. .. rst-class:: classref-introduction-group Description ----------- -Pan gesture is performed when the user swipes the touch screen with two fingers. It's typically used for panning/scrolling. +Stores information about pan gestures. A pan gesture is performed when the user swipes the touch screen with two fingers. It's typically used for panning/scrolling. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventscreendrag.rst b/classes/class_inputeventscreendrag.rst index 0b5177879ee..c1d47f63da1 100644 --- a/classes/class_inputeventscreendrag.rst +++ b/classes/class_inputeventscreendrag.rst @@ -12,21 +12,21 @@ InputEventScreenDrag **Inherits:** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for screen drag events. Only available on mobile devices. +Represents a screen drag event. .. rst-class:: classref-introduction-group Description ----------- -Contains screen drag information. See :ref:`Node._input`. +Stores information about screen drag events. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventscreentouch.rst b/classes/class_inputeventscreentouch.rst index ad4d3e4d91d..1d5f6cd8546 100644 --- a/classes/class_inputeventscreentouch.rst +++ b/classes/class_inputeventscreentouch.rst @@ -12,23 +12,21 @@ InputEventScreenTouch **Inherits:** :ref:`InputEventFromWindow` **<** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Input event type for screen touch events. - -(only available on mobile devices) +Represents a screen touch event. .. rst-class:: classref-introduction-group Description ----------- -Stores multi-touch press/release information. Supports touch press, touch release and :ref:`index` for multi-touch count and order. +Stores information about multi-touch press/release input events. Supports touch press, touch release and :ref:`index` for multi-touch count and order. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventshortcut.rst b/classes/class_inputeventshortcut.rst index 392c478b742..12c6aaf760a 100644 --- a/classes/class_inputeventshortcut.rst +++ b/classes/class_inputeventshortcut.rst @@ -12,14 +12,14 @@ InputEventShortcut **Inherits:** :ref:`InputEvent` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`InputEvent` that signifies a triggered keyboard :ref:`Shortcut`. +Represents a triggered keyboard :ref:`Shortcut`. .. rst-class:: classref-introduction-group Description ----------- -InputEventShortcut is a special event that can be received in :ref:`Node._unhandled_key_input`. It's typically sent by the editor's Command Palette to trigger actions, but can also be sent manually using :ref:`Viewport.push_unhandled_input`. +InputEventShortcut is a special event that can be received in :ref:`Node._unhandled_key_input`. It is typically sent by the editor's Command Palette to trigger actions, but can also be sent manually using :ref:`Viewport.push_input`. .. rst-class:: classref-reftable-group diff --git a/classes/class_inputeventwithmodifiers.rst b/classes/class_inputeventwithmodifiers.rst index e3e1f0488c1..5b8eab0acec 100644 --- a/classes/class_inputeventwithmodifiers.rst +++ b/classes/class_inputeventwithmodifiers.rst @@ -14,21 +14,21 @@ InputEventWithModifiers **Inherited By:** :ref:`InputEventGesture`, :ref:`InputEventKey`, :ref:`InputEventMouse` -Base class for keys events with modifiers. +Abstract base class for input events affected by modifier keys like :kbd:`Shift` and :kbd:`Alt`. .. rst-class:: classref-introduction-group Description ----------- -Contains keys events information with modifiers support like :kbd:`Shift` or :kbd:`Alt`. See :ref:`Node._input`. +Stores information about mouse, keyboard, and touch gesture input events. This includes information about which modifier keys are pressed, such as :kbd:`Shift` or :kbd:`Alt`. See :ref:`Node._input`. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`InputEvent <../tutorials/inputs/inputevent>` +- :doc:`Using InputEvent <../tutorials/inputs/inputevent>` .. rst-class:: classref-reftable-group diff --git a/classes/class_inputmap.rst b/classes/class_inputmap.rst index efe9d5373d7..2902bd71cc9 100644 --- a/classes/class_inputmap.rst +++ b/classes/class_inputmap.rst @@ -12,7 +12,7 @@ InputMap **Inherits:** :ref:`Object` -Singleton that manages :ref:`InputEventAction`. +A singleton that manages all :ref:`InputEventAction`\ s. .. rst-class:: classref-introduction-group @@ -26,7 +26,7 @@ Manages all :ref:`InputEventAction` which can be created Tutorials --------- -- `InputEvent: InputMap <../tutorials/inputs/inputevent.html#inputmap>`__ +- `Using InputEvent: InputMap <../tutorials/inputs/inputevent.html#inputmap>`__ .. rst-class:: classref-reftable-group diff --git a/classes/class_int.rst b/classes/class_int.rst index 2dda122c1fa..3b3cf8ad25a 100644 --- a/classes/class_int.rst +++ b/classes/class_int.rst @@ -10,7 +10,7 @@ int === -Built-in integer Variant type. +A built-in type for integers. .. rst-class:: classref-introduction-group diff --git a/classes/class_itemlist.rst b/classes/class_itemlist.rst index 7d65c664dd4..23b687fd9ee 100644 --- a/classes/class_itemlist.rst +++ b/classes/class_itemlist.rst @@ -12,20 +12,20 @@ ItemList **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control that provides a list of selectable items (and/or icons) in a single column, or optionally in multiple columns. +A vertical list of selectable items with one or multiple columns. .. rst-class:: classref-introduction-group Description ----------- -This control provides a selectable list of items that may be in a single (or multiple columns) with option of text, icons, or both text and icon. Tooltips are supported and may be different for every item in the list. +This control provides a vertical list of selectable items that may be in a single or in multiple columns, with each item having options for text and an icon. Tooltips are supported and may be different for every item in the list. Selectable items in the list may be selected or deselected and multiple selection may be enabled. Selection with right mouse button may also be enabled to allow use of popup context menus. Items may also be "activated" by double-clicking them or by pressing :kbd:`Enter`. -Item text only supports single-line strings, newline characters (e.g. ``\n``) in the string won't produce a newline. Text wrapping is enabled in :ref:`ICON_MODE_TOP` mode, but column's width is adjusted to fully fit its content by default. You need to set :ref:`fixed_column_width` greater than zero to wrap the text. +Item text only supports single-line strings. Newline characters (e.g. ``\n``) in the string won't produce a newline. Text wrapping is enabled in :ref:`ICON_MODE_TOP` mode, but the column's width is adjusted to fully fit its content by default. You need to set :ref:`fixed_column_width` greater than zero to wrap the text. -All ``set_*`` methods allow negative item index, which makes the item accessed from the last one. +All ``set_*`` methods allow negative item indices, i.e. ``-1`` to access the last item, ``-2`` to select the second-to-last item, and so on. \ **Incremental search:** Like :ref:`PopupMenu` and :ref:`Tree`, **ItemList** supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing :ref:`ProjectSettings.gui/timers/incremental_search_max_interval_msec`. diff --git a/classes/class_javascriptobject.rst b/classes/class_javascriptobject.rst index ec7c6688e00..65dafaadaf8 100644 --- a/classes/class_javascriptobject.rst +++ b/classes/class_javascriptobject.rst @@ -27,7 +27,7 @@ JavaScriptObject is used to interact with JavaScript objects retrieved or create extends Node - var _my_js_callback = JavaScriptBridge.create_callback(self, "myCallback") # This reference must be kept + var _my_js_callback = JavaScriptBridge.create_callback(myCallback) # This reference must be kept var console = JavaScriptBridge.get_interface("console") func _init(): diff --git a/classes/class_joint2d.rst b/classes/class_joint2d.rst index 92a1a40c39b..e08e3521df0 100644 --- a/classes/class_joint2d.rst +++ b/classes/class_joint2d.rst @@ -14,14 +14,14 @@ Joint2D **Inherited By:** :ref:`DampedSpringJoint2D`, :ref:`GrooveJoint2D`, :ref:`PinJoint2D` -Base node for all joint constraints in 2D physics. +Abstract base class for all 2D physics joints. .. rst-class:: classref-introduction-group Description ----------- -Base node for all joint constraints in 2D physics. Joints take 2 bodies and apply a custom constraint. +Abstract base class for all joints in 2D physics. 2D joints bind together two physics bodies and apply a constraint. .. rst-class:: classref-reftable-group diff --git a/classes/class_joint3d.rst b/classes/class_joint3d.rst index 716b348686d..487f13cc9b7 100644 --- a/classes/class_joint3d.rst +++ b/classes/class_joint3d.rst @@ -14,14 +14,14 @@ Joint3D **Inherited By:** :ref:`ConeTwistJoint3D`, :ref:`Generic6DOFJoint3D`, :ref:`HingeJoint3D`, :ref:`PinJoint3D`, :ref:`SliderJoint3D` -Base class for all 3D joints. +Abstract base class for all 3D physics joints. .. rst-class:: classref-introduction-group Description ----------- -Joints are used to bind together two physics bodies. They have a solver priority and can define if the bodies of the two attached nodes should be able to collide with each other. See also :ref:`Generic6DOFJoint3D`. +Abstract base class for all joints in 3D physics. 3D joints bind together two physics bodies and apply a constraint. .. rst-class:: classref-introduction-group diff --git a/classes/class_kinematiccollision2d.rst b/classes/class_kinematiccollision2d.rst index ed9b00d88d3..ced69cc9629 100644 --- a/classes/class_kinematiccollision2d.rst +++ b/classes/class_kinematiccollision2d.rst @@ -12,16 +12,16 @@ KinematicCollision2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Collision data for :ref:`PhysicsBody2D.move_and_collide` collisions. +Holds collision data from the movement of a :ref:`PhysicsBody2D`. .. rst-class:: classref-introduction-group Description ----------- -Contains collision data for :ref:`PhysicsBody2D.move_and_collide` collisions. When a :ref:`PhysicsBody2D` is moved using :ref:`PhysicsBody2D.move_and_collide`, it stops if it detects a collision with another body. If a collision is detected, a **KinematicCollision2D** object is returned. +Holds collision data from the movement of a :ref:`PhysicsBody2D`, usually from :ref:`PhysicsBody2D.move_and_collide`. When a :ref:`PhysicsBody2D` is moved, it stops if it detects a collision with another body. If a collision is detected, a **KinematicCollision2D** object is returned. -This object contains information about the collision, including the colliding object, the remaining motion, and the collision position. This information can be used to calculate a collision response. +The collision data includes the colliding object, the remaining motion, and the collision position. This data can be used to determine a custom response to the collision. .. rst-class:: classref-reftable-group diff --git a/classes/class_kinematiccollision3d.rst b/classes/class_kinematiccollision3d.rst index 9faace40d05..1ddd6c170a5 100644 --- a/classes/class_kinematiccollision3d.rst +++ b/classes/class_kinematiccollision3d.rst @@ -12,16 +12,16 @@ KinematicCollision3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Collision data for :ref:`PhysicsBody3D.move_and_collide` collisions. +Holds collision data from the movement of a :ref:`PhysicsBody3D`. .. rst-class:: classref-introduction-group Description ----------- -Contains collision data for :ref:`PhysicsBody3D.move_and_collide` collisions. When a :ref:`PhysicsBody3D` is moved using :ref:`PhysicsBody3D.move_and_collide`, it stops if it detects a collision with another body. If a collision is detected, a **KinematicCollision3D** object is returned. +Holds collision data from the movement of a :ref:`PhysicsBody3D`, usually from :ref:`PhysicsBody3D.move_and_collide`. When a :ref:`PhysicsBody3D` is moved, it stops if it detects a collision with another body. If a collision is detected, a **KinematicCollision3D** object is returned. -This object contains information about the collision, including the colliding object, the remaining motion, and the collision position. This information can be used to calculate a collision response. +The collision data includes the colliding object, the remaining motion, and the collision position. This data can be used to determine a custom response to the collision. .. rst-class:: classref-reftable-group diff --git a/classes/class_label.rst b/classes/class_label.rst index 4f5b011e868..ca23a6d6c2a 100644 --- a/classes/class_label.rst +++ b/classes/class_label.rst @@ -12,16 +12,14 @@ Label **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Displays plain text in a line or wrapped inside a rectangle. For formatted text, use :ref:`RichTextLabel`. +A control for displaying plain text. .. rst-class:: classref-introduction-group Description ----------- -Label displays plain text on the screen. It gives you control over the horizontal and vertical alignment and can wrap the text inside the node's bounding rectangle. It doesn't support bold, italics, or other formatting. For that, use :ref:`RichTextLabel` instead. - -\ **Note:** Contrarily to most other :ref:`Control`\ s, Label's :ref:`Control.mouse_filter` defaults to :ref:`Control.MOUSE_FILTER_IGNORE` (i.e. it doesn't react to mouse input events). This implies that a label won't display any configured :ref:`Control.tooltip_text`, unless you change its mouse filter. +A control for displaying plain text. It gives you control over the horizontal and vertical alignment and can wrap the text inside the node's bounding rectangle. It doesn't support bold, italics, or other rich text formatting. For that, use :ref:`RichTextLabel` instead. .. rst-class:: classref-introduction-group diff --git a/classes/class_label3d.rst b/classes/class_label3d.rst index 134872eb155..9e3e0635a96 100644 --- a/classes/class_label3d.rst +++ b/classes/class_label3d.rst @@ -12,14 +12,14 @@ Label3D **Inherits:** :ref:`GeometryInstance3D` **<** :ref:`VisualInstance3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Displays plain text in a 3D world. +A node for displaying plain text in 3D space. .. rst-class:: classref-introduction-group Description ----------- -Label3D displays plain text in a 3D world. It gives you control over the horizontal and vertical alignment. +A node for displaying plain text in 3D space. By adjusting various properties of this node, you can configure things such as the text's appearance and whether it always faces the camera. .. rst-class:: classref-reftable-group diff --git a/classes/class_labelsettings.rst b/classes/class_labelsettings.rst index 69544c2b94f..c7e784e8bf9 100644 --- a/classes/class_labelsettings.rst +++ b/classes/class_labelsettings.rst @@ -12,14 +12,14 @@ LabelSettings **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Collection of common settings to customize label text. +Provides common settings to customize the text in a :ref:`Label`. .. rst-class:: classref-introduction-group Description ----------- -**LabelSettings** is a resource that can be assigned to a :ref:`Label` node to customize it. It will take priority over the properties defined in theme. The resource can be shared between multiple labels and swapped on the fly, so it's convenient and flexible way to setup text style. +**LabelSettings** is a resource that provides common settings to customize the text in a :ref:`Label`. It will take priority over the properties defined in :ref:`Control.theme`. The resource can be shared between multiple labels and changed on the fly, so it's convenient and flexible way to setup text style. .. rst-class:: classref-reftable-group diff --git a/classes/class_lineedit.rst b/classes/class_lineedit.rst index 3974d0e48b7..77f59193054 100644 --- a/classes/class_lineedit.rst +++ b/classes/class_lineedit.rst @@ -12,16 +12,14 @@ LineEdit **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control that provides single-line string editing. +An input field for single-line text. .. rst-class:: classref-introduction-group Description ----------- -LineEdit provides a single-line string editor, used for text fields. - -It features many built-in shortcuts which will always be available (:kbd:`Ctrl` here maps to :kbd:`Cmd` on macOS): +**LineEdit** provides an input field for editing a single line of text. It features many built-in shortcuts that are always available (:kbd:`Ctrl` here maps to :kbd:`Cmd` on macOS): - :kbd:`Ctrl + C`: Copy @@ -45,21 +43,21 @@ It features many built-in shortcuts which will always be available (:kbd:`Ctrl` On macOS, some extra keyboard shortcuts are available: -- :kbd:`Ctrl + F`: Same as :kbd:`Right Arrow`, move the caret one character right +- :kbd:`Cmd + F`: Same as :kbd:`Right Arrow`, move the caret one character right -- :kbd:`Ctrl + B`: Same as :kbd:`Left Arrow`, move the caret one character left +- :kbd:`Cmd + B`: Same as :kbd:`Left Arrow`, move the caret one character left -- :kbd:`Ctrl + P`: Same as :kbd:`Up Arrow`, move the caret to the previous line +- :kbd:`Cmd + P`: Same as :kbd:`Up Arrow`, move the caret to the previous line -- :kbd:`Ctrl + N`: Same as :kbd:`Down Arrow`, move the caret to the next line +- :kbd:`Cmd + N`: Same as :kbd:`Down Arrow`, move the caret to the next line -- :kbd:`Ctrl + D`: Same as :kbd:`Delete`, delete the character on the right side of caret +- :kbd:`Cmd + D`: Same as :kbd:`Delete`, delete the character on the right side of caret -- :kbd:`Ctrl + H`: Same as :kbd:`Backspace`, delete the character on the left side of the caret +- :kbd:`Cmd + H`: Same as :kbd:`Backspace`, delete the character on the left side of the caret -- :kbd:`Ctrl + A`: Same as :kbd:`Home`, move the caret to the beginning of the line +- :kbd:`Cmd + A`: Same as :kbd:`Home`, move the caret to the beginning of the line -- :kbd:`Ctrl + E`: Same as :kbd:`End`, move the caret to the end of the line +- :kbd:`Cmd + E`: Same as :kbd:`End`, move the caret to the end of the line - :kbd:`Cmd + Left Arrow`: Same as :kbd:`Home`, move the caret to the beginning of the line diff --git a/classes/class_linkbutton.rst b/classes/class_linkbutton.rst index 7457312514d..aad5d7b8a0d 100644 --- a/classes/class_linkbutton.rst +++ b/classes/class_linkbutton.rst @@ -12,14 +12,14 @@ LinkButton **Inherits:** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Simple button used to represent a link to some resource. +A button that represents a link. .. rst-class:: classref-introduction-group Description ----------- -This kind of button is primarily used when the interaction with the button causes a context change (like linking to a web page). +A button that represents a link. This type of button is primarily used for interactions that cause a context change (like linking to a web page). See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_margincontainer.rst b/classes/class_margincontainer.rst index 6aa202fefce..4678c955817 100644 --- a/classes/class_margincontainer.rst +++ b/classes/class_margincontainer.rst @@ -12,16 +12,16 @@ MarginContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Simple margin container. +A container that keeps a margin around its child controls. .. rst-class:: classref-introduction-group Description ----------- -Adds a top, left, bottom, and right margin to all :ref:`Control` nodes that are direct children of the container. To control the **MarginContainer**'s margin, use the ``margin_*`` theme properties listed below. +**MarginContainer** adds an adjustable margin on each side of its child controls. The margins are added around all children, not around each individual one. To control the **MarginContainer**'s margins, use the ``margin_*`` theme properties listed below. -\ **Note:** Be careful, :ref:`Control` margin values are different from the constant margin values. If you want to change the custom margin values of the **MarginContainer** by code, you should use the following examples: +\ **Note:** The margin sizes are theme overrides, not normal properties. This is an example of how to change them in code: .. tabs:: @@ -51,7 +51,7 @@ Adds a top, left, bottom, and right margin to all :ref:`Control` Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_menubar.rst b/classes/class_menubar.rst index cbf890b18bf..984facc726f 100644 --- a/classes/class_menubar.rst +++ b/classes/class_menubar.rst @@ -12,14 +12,14 @@ MenuBar **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -A horizontal menu bar, which displays :ref:`PopupMenu`\ s or system global menu. +A horizontal menu bar that creates a :ref:`MenuButton` for each :ref:`PopupMenu` child. .. rst-class:: classref-introduction-group Description ----------- -New items can be created by adding :ref:`PopupMenu` nodes to this node. +A horizontal menu bar that creates a :ref:`MenuButton` for each :ref:`PopupMenu` child. New items are created by adding :ref:`PopupMenu`\ s to this node. .. rst-class:: classref-reftable-group diff --git a/classes/class_menubutton.rst b/classes/class_menubutton.rst index 3421950e124..8d09a3f1687 100644 --- a/classes/class_menubutton.rst +++ b/classes/class_menubutton.rst @@ -12,16 +12,14 @@ MenuButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Special button that brings up a :ref:`PopupMenu` when clicked. +A button that brings up a :ref:`PopupMenu` when clicked. .. rst-class:: classref-introduction-group Description ----------- -Special button that brings up a :ref:`PopupMenu` when clicked. - -New items can be created inside this :ref:`PopupMenu` using ``get_popup().add_item("My Item Name")``. You can also create them directly from the editor. To do so, select the **MenuButton** node, then in the toolbar at the top of the 2D editor, click **Items** then click **Add** in the popup. You will be able to give each item new properties. +A button that brings up a :ref:`PopupMenu` when clicked. To create new items inside this :ref:`PopupMenu`, use ``get_popup().add_item("My Item Name")``. You can also create them directly from Godot editor's inspector. See also :ref:`BaseButton` which contains common properties and methods associated with this node. diff --git a/classes/class_mesh.rst b/classes/class_mesh.rst index 0385cf53c03..f99358c3b04 100644 --- a/classes/class_mesh.rst +++ b/classes/class_mesh.rst @@ -229,7 +229,7 @@ enum **ArrayType**: :ref:`ArrayType` **ARRAY_CUSTOM0** = ``6`` -Contains custom color channel 0. :ref:`PackedByteArray` if ``(format >> [constant ARRAY_FORMAT_CUSTOM0_SHIFT]) & [constant ARRAY_FORMAT_CUSTOM_MASK])`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. +Contains custom color channel 0. :ref:`PackedByteArray` if ``(format >> Mesh.ARRAY_FORMAT_CUSTOM0_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. .. _class_Mesh_constant_ARRAY_CUSTOM1: @@ -237,7 +237,7 @@ Contains custom color channel 0. :ref:`PackedByteArray` i :ref:`ArrayType` **ARRAY_CUSTOM1** = ``7`` -Contains custom color channel 1. :ref:`PackedByteArray` if ``(format >> [constant ARRAY_FORMAT_CUSTOM1_SHIFT]) & [constant ARRAY_FORMAT_CUSTOM_MASK])`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. +Contains custom color channel 1. :ref:`PackedByteArray` if ``(format >> Mesh.ARRAY_FORMAT_CUSTOM1_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. .. _class_Mesh_constant_ARRAY_CUSTOM2: @@ -245,7 +245,7 @@ Contains custom color channel 1. :ref:`PackedByteArray` i :ref:`ArrayType` **ARRAY_CUSTOM2** = ``8`` -Contains custom color channel 2. :ref:`PackedByteArray` if ``(format >> [constant ARRAY_FORMAT_CUSTOM2_SHIFT]) & [constant ARRAY_FORMAT_CUSTOM_MASK])`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. +Contains custom color channel 2. :ref:`PackedByteArray` if ``(format >> Mesh.ARRAY_FORMAT_CUSTOM2_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. .. _class_Mesh_constant_ARRAY_CUSTOM3: @@ -253,7 +253,7 @@ Contains custom color channel 2. :ref:`PackedByteArray` i :ref:`ArrayType` **ARRAY_CUSTOM3** = ``9`` -Contains custom color channel 3. :ref:`PackedByteArray` if ``(format >> [constant ARRAY_FORMAT_CUSTOM3_SHIFT]) & [constant ARRAY_FORMAT_CUSTOM_MASK])`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. +Contains custom color channel 3. :ref:`PackedByteArray` if ``(format >> Mesh.ARRAY_FORMAT_CUSTOM3_SHIFT) & Mesh.ARRAY_FORMAT_CUSTOM_MASK`` is :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RGBA8_UNORM`, :ref:`ARRAY_CUSTOM_RG_HALF` or :ref:`ARRAY_CUSTOM_RGBA_HALF`. :ref:`PackedFloat32Array` otherwise. .. _class_Mesh_constant_ARRAY_BONES: diff --git a/classes/class_missingnode.rst b/classes/class_missingnode.rst index 0e9f519842c..d9562674516 100644 --- a/classes/class_missingnode.rst +++ b/classes/class_missingnode.rst @@ -12,7 +12,7 @@ MissingNode **Inherits:** :ref:`Node` **<** :ref:`Object` -This is an internal editor class intended for keeping data of nodes of unknown type. +An internal editor class intended for keeping the data of unrecognized nodes. .. rst-class:: classref-introduction-group @@ -55,9 +55,7 @@ Property Descriptions - void **set_original_class** **(** :ref:`String` value **)** - :ref:`String` **get_original_class** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Returns the name of the type this node was originally. .. rst-class:: classref-item-separator diff --git a/classes/class_missingresource.rst b/classes/class_missingresource.rst index d912a25b42e..d458b706331 100644 --- a/classes/class_missingresource.rst +++ b/classes/class_missingresource.rst @@ -12,7 +12,7 @@ MissingResource **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -This is an internal editor class intended for keeping data of resources of unknown type. +An internal editor class intended for keeping the data of unrecognized resources. .. rst-class:: classref-introduction-group @@ -55,9 +55,7 @@ Property Descriptions - void **set_original_class** **(** :ref:`String` value **)** - :ref:`String` **get_original_class** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Returns the name of the class this resource was originally. .. rst-class:: classref-item-separator diff --git a/classes/class_mutex.rst b/classes/class_mutex.rst index 11492e01119..b72ae9b2e8c 100644 --- a/classes/class_mutex.rst +++ b/classes/class_mutex.rst @@ -12,24 +12,24 @@ Mutex **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A synchronization mutex (mutual exclusion). +A binary :ref:`Semaphore` for synchronization of multiple :ref:`Thread`\ s. .. rst-class:: classref-introduction-group Description ----------- -A synchronization mutex (mutual exclusion). This is used to synchronize multiple :ref:`Thread`\ s, and is equivalent to a binary :ref:`Semaphore`. It guarantees that only one thread can ever acquire the lock at a time. A mutex can be used to protect a critical section; however, be careful to avoid deadlocks. +A synchronization mutex (mutual exclusion). This is used to synchronize multiple :ref:`Thread`\ s, and is equivalent to a binary :ref:`Semaphore`. It guarantees that only one thread can access a critical section at a time. -It's of the recursive kind, so it can be locked multiple times by one thread, provided it also unlocks it as many times. +This is a reentrant mutex, meaning that it can be locked multiple times by one thread, provided it also unlocks it as many times. -\ **Warning:**\ +\ **Warning:** Mutexes must be used carefully to avoid deadlocks. -To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met: +\ **Warning:** To ensure proper cleanup without crashes or deadlocks, the following conditions must be met: -- By the time a **Mutex**'s reference count reaches zero and therefore it is destroyed, no threads (including the one on which the destruction will happen) must have it locked. +- When a **Mutex**'s reference count reaches zero and it is therefore destroyed, no threads (including the one on which the destruction will happen) must have it locked. -- By the time a :ref:`Thread`'s reference count reaches zero and therefore it is destroyed, it must not have any mutex locked. +- When a :ref:`Thread`'s reference count reaches zero and it is therefore destroyed, it must not have any mutex locked. .. rst-class:: classref-introduction-group @@ -38,6 +38,8 @@ Tutorials - :doc:`Using multiple threads <../tutorials/performance/using_multiple_threads>` +- :doc:`Thread-safe APIs <../tutorials/performance/thread_safe_apis>` + .. rst-class:: classref-reftable-group Methods diff --git a/classes/class_navigationagent2d.rst b/classes/class_navigationagent2d.rst index b94c579c517..2e1a4fe646f 100644 --- a/classes/class_navigationagent2d.rst +++ b/classes/class_navigationagent2d.rst @@ -12,16 +12,18 @@ NavigationAgent2D **Inherits:** :ref:`Node` **<** :ref:`Object` -2D Agent used in navigation for collision avoidance. +A 2D agent used to pathfind to a position while avoiding obstacles. .. rst-class:: classref-introduction-group Description ----------- -2D Agent that is used in navigation to reach a position while avoiding static and dynamic obstacles. The dynamic obstacles are avoided using RVO collision avoidance. The agent needs navigation data to work correctly. **NavigationAgent2D** is physics safe. +A 2D agent used to pathfind to a position while avoiding static and dynamic obstacles. The calculation can be used by the parent node to dynamically move it along the path. Requires navigation data to work correctly. -\ **Note:** After :ref:`target_position` is set, the :ref:`get_next_path_position` function must be used once every physics frame to update the internal path logic of the NavigationAgent. The returned position from this function should be used as the next movement position for the agent's parent node. +Dynamic obstacles are avoided using RVO collision avoidance. Avoidance is computed before physics, so the pathfinding information can be used safely in the physics step. + +\ **Note:** After setting the :ref:`target_position` property, the :ref:`get_next_path_position` method must be used once every physics frame to update the internal path logic of the navigation agent. The vector position it returns should be used as the next movement position for the agent's parent node. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationagent3d.rst b/classes/class_navigationagent3d.rst index c98317be1f8..a5bbda67413 100644 --- a/classes/class_navigationagent3d.rst +++ b/classes/class_navigationagent3d.rst @@ -12,16 +12,18 @@ NavigationAgent3D **Inherits:** :ref:`Node` **<** :ref:`Object` -3D Agent used in navigation for collision avoidance. +A 3D agent used to pathfind to a position while avoiding obstacles. .. rst-class:: classref-introduction-group Description ----------- -3D Agent that is used in navigation to reach a position while avoiding static and dynamic obstacles. The dynamic obstacles are avoided using RVO collision avoidance. The agent needs navigation data to work correctly. **NavigationAgent3D** is physics safe. +A 3D agent used to pathfind to a position while avoiding static and dynamic obstacles. The calculation can be used by the parent node to dynamically move it along the path. Requires navigation data to work correctly. -\ **Note:** After :ref:`target_position` is set, the :ref:`get_next_path_position` function must be used once every physics frame to update the internal path logic of the NavigationAgent. The returned position from this function should be used as the next movement position for the agent's parent node. +Dynamic obstacles are avoided using RVO collision avoidance. Avoidance is computed before physics, so the pathfinding information can be used safely in the physics step. + +\ **Note:** After setting the :ref:`target_position` property, the :ref:`get_next_path_position` method must be used once every physics frame to update the internal path logic of the navigation agent. The vector position it returns should be used as the next movement position for the agent's parent node. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationlink2d.rst b/classes/class_navigationlink2d.rst index 914ac5c3dda..229399a65aa 100644 --- a/classes/class_navigationlink2d.rst +++ b/classes/class_navigationlink2d.rst @@ -12,14 +12,14 @@ NavigationLink2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Creates a link between two positions that :ref:`NavigationServer2D` can route agents through. +A link between two positions on :ref:`NavigationRegion2D`\ s that agents can be routed through. .. rst-class:: classref-introduction-group Description ----------- -Creates a link between two positions that :ref:`NavigationServer2D` can route agents through. Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps. +A link between two positions on :ref:`NavigationRegion2D`\ s that agents can be routed through. These positions can be on the same :ref:`NavigationRegion2D` or on two different ones. Links are useful to express navigation methods other than traveling along the surface of the navigation polygon, such as ziplines, teleporters, or gaps that can be jumped across. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationlink3d.rst b/classes/class_navigationlink3d.rst index 4cb049409a7..73a74804652 100644 --- a/classes/class_navigationlink3d.rst +++ b/classes/class_navigationlink3d.rst @@ -12,14 +12,14 @@ NavigationLink3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Creates a link between two positions that :ref:`NavigationServer3D` can route agents through. +A link between two positions on :ref:`NavigationRegion3D`\ s that agents can be routed through. .. rst-class:: classref-introduction-group Description ----------- -Creates a link between two positions that :ref:`NavigationServer3D` can route agents through. Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps. +A link between two positions on :ref:`NavigationRegion3D`\ s that agents can be routed through. These positions can be on the same :ref:`NavigationRegion3D` or on two different ones. Links are useful to express navigation methods other than traveling along the surface of the navigation mesh, such as ziplines, teleporters, or gaps that can be jumped across. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationmesh.rst b/classes/class_navigationmesh.rst index ad344ef28c6..9d9b6ead509 100644 --- a/classes/class_navigationmesh.rst +++ b/classes/class_navigationmesh.rst @@ -12,7 +12,7 @@ NavigationMesh **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A mesh to approximate the walkable areas and obstacles. +A navigation mesh that defines traversable areas and obstacles. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationpathqueryparameters2d.rst b/classes/class_navigationpathqueryparameters2d.rst index 7b9afc06da4..30b73f6c414 100644 --- a/classes/class_navigationpathqueryparameters2d.rst +++ b/classes/class_navigationpathqueryparameters2d.rst @@ -12,14 +12,14 @@ NavigationPathQueryParameters2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 2D navigation path query. +Provides parameters for 2D navigation path queries. .. rst-class:: classref-introduction-group Description ----------- -This class contains the start and target position and other parameters to be used with :ref:`NavigationServer2D.query_path`. +By changing various properties of this object, such as the start and target position, you can configure path queries to the :ref:`NavigationServer2D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationpathqueryparameters3d.rst b/classes/class_navigationpathqueryparameters3d.rst index 9e82b79e093..50ddf2c85fb 100644 --- a/classes/class_navigationpathqueryparameters3d.rst +++ b/classes/class_navigationpathqueryparameters3d.rst @@ -12,14 +12,14 @@ NavigationPathQueryParameters3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 3D navigation path query. +Provides parameters for 3D navigation path queries. .. rst-class:: classref-introduction-group Description ----------- -This class contains the start and target position and other parameters to be used with :ref:`NavigationServer3D.query_path`. +By changing various properties of this object, such as the start and target position, you can configure path queries to the :ref:`NavigationServer3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationpathqueryresult2d.rst b/classes/class_navigationpathqueryresult2d.rst index e43afa25a40..f9f1e14da97 100644 --- a/classes/class_navigationpathqueryresult2d.rst +++ b/classes/class_navigationpathqueryresult2d.rst @@ -12,14 +12,14 @@ NavigationPathQueryResult2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Result from a :ref:`NavigationPathQueryParameters2D` navigation path query. +Represents the result of a 2D pathfinding query. .. rst-class:: classref-introduction-group Description ----------- -This class contains the result of a navigation path query from :ref:`NavigationServer2D.query_path`. +This class stores the result of a 2D navigation path query from the :ref:`NavigationServer2D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationpathqueryresult3d.rst b/classes/class_navigationpathqueryresult3d.rst index a1c7fe2484b..be5da0aee5a 100644 --- a/classes/class_navigationpathqueryresult3d.rst +++ b/classes/class_navigationpathqueryresult3d.rst @@ -12,14 +12,14 @@ NavigationPathQueryResult3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Result from a :ref:`NavigationPathQueryParameters3D` navigation path query. +Represents the result of a 3D pathfinding query. .. rst-class:: classref-introduction-group Description ----------- -This class contains the result of a navigation path query from :ref:`NavigationServer3D.query_path`. +This class stores the result of a 3D navigation path query from the :ref:`NavigationServer3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationpolygon.rst b/classes/class_navigationpolygon.rst index 2303b61510a..79d5e909765 100644 --- a/classes/class_navigationpolygon.rst +++ b/classes/class_navigationpolygon.rst @@ -12,7 +12,7 @@ NavigationPolygon **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A node that has methods to draw outlines or use indices of vertices to create navigation polygons. +A navigation polygon that defines traversable areas and obstacles. .. rst-class:: classref-introduction-group diff --git a/classes/class_navigationregion2d.rst b/classes/class_navigationregion2d.rst index 3d066fbd14d..2a156c76fda 100644 --- a/classes/class_navigationregion2d.rst +++ b/classes/class_navigationregion2d.rst @@ -12,20 +12,20 @@ NavigationRegion2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -A region of the 2D navigation map. +A traversable 2D region that :ref:`NavigationAgent2D`\ s can use for pathfinding. .. rst-class:: classref-introduction-group Description ----------- -A region of the navigation map. It tells the :ref:`NavigationServer2D` what can be navigated and what cannot, based on its :ref:`NavigationPolygon` resource. +A traversable 2D region based on a :ref:`NavigationPolygon` that :ref:`NavigationAgent2D`\ s can use for pathfinding. Two regions can be connected to each other if they share a similar edge. You can set the minimum distance between two vertices required to connect two edges by using :ref:`NavigationServer2D.map_set_edge_connection_margin`. \ **Note:** Overlapping two regions' navigation polygons is not enough for connecting two regions. They must share a similar edge. -The pathfinding cost of entering this region from another region can be controlled with the :ref:`enter_cost` value. +The pathfinding cost of entering a region from another region can be controlled with the :ref:`enter_cost` value. \ **Note:** This value is not added to the path cost when the start position is already inside this region. diff --git a/classes/class_navigationregion3d.rst b/classes/class_navigationregion3d.rst index 347981d53df..f5c5a6f0df6 100644 --- a/classes/class_navigationregion3d.rst +++ b/classes/class_navigationregion3d.rst @@ -12,14 +12,14 @@ NavigationRegion3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -A region of the navigation map. +A traversable 3D region that :ref:`NavigationAgent3D`\ s can use for pathfinding. .. rst-class:: classref-introduction-group Description ----------- -A region of the navigation map. It tells the :ref:`NavigationServer3D` what can be navigated and what cannot, based on its :ref:`NavigationMesh` resource. +A traversable 3D region based on a :ref:`NavigationMesh` that :ref:`NavigationAgent3D`\ s can use for pathfinding. Two regions can be connected to each other if they share a similar edge. You can set the minimum distance between two vertices required to connect two edges by using :ref:`NavigationServer3D.map_set_edge_connection_margin`. diff --git a/classes/class_navigationserver2d.rst b/classes/class_navigationserver2d.rst index 59003bcc106..f111b9071d5 100644 --- a/classes/class_navigationserver2d.rst +++ b/classes/class_navigationserver2d.rst @@ -12,26 +12,26 @@ NavigationServer2D **Inherits:** :ref:`Object` -Server interface for low-level 2D navigation access. +A server interface for low-level 2D navigation access. .. rst-class:: classref-introduction-group Description ----------- -NavigationServer2D is the server responsible for all 2D navigation. It handles several objects, namely maps, regions and agents. +NavigationServer2D is the server that handles navigation maps, regions and agents. It does not handle A\* navigation from :ref:`AStar2D` or :ref:`AStarGrid2D`. -Maps are made up of regions, which are made of navigation polygons. Together, they define the navigable areas in the 2D world. +Maps are made up of regions, which are made of navigation polygons. Together, they define the traversable areas in the 2D world. -\ **Note:** Most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation related Nodes in the SceneTree or made through scripts. +\ **Note:** Most **NavigationServer2D** changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation-related nodes in the scene tree or made through scripts. For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than ``edge_connection_margin`` to the respective other edge's vertex. -You may assign navigation layers to regions with :ref:`region_set_navigation_layers`, which then can be checked upon when requesting a path with :ref:`map_get_path`. This allows allowing or forbidding some areas to 2D objects. +You may assign navigation layers to regions with :ref:`region_set_navigation_layers`, which then can be checked upon when requesting a path with :ref:`map_get_path`. This can be used to allow or deny certain areas for some objects. To use the collision avoidance system, you may use agents. You can set an agent's target velocity, then the servers will emit a callback with a modified velocity. -\ **Note:** The collision avoidance system ignores regions. Using the modified velocity as-is might lead to pushing an agent outside of a navigable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine. +\ **Note:** The collision avoidance system ignores regions. Using the modified velocity directly may move an agent outside of the traversable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine. This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying. diff --git a/classes/class_navigationserver3d.rst b/classes/class_navigationserver3d.rst index 8d7210ccc99..da06c78b050 100644 --- a/classes/class_navigationserver3d.rst +++ b/classes/class_navigationserver3d.rst @@ -12,26 +12,26 @@ NavigationServer3D **Inherits:** :ref:`Object` -Server interface for low-level 3D navigation access. +A server interface for low-level 3D navigation access. .. rst-class:: classref-introduction-group Description ----------- -NavigationServer3D is the server responsible for all 3D navigation. It handles several objects, namely maps, regions and agents. +NavigationServer2D is the server that handles navigation maps, regions and agents. It does not handle A\* navigation from :ref:`AStar3D`. Maps are made up of regions, which are made of navigation meshes. Together, they define the navigable areas in the 3D world. -\ **Note:** Most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation related Nodes in the SceneTree or made through scripts. +\ **Note:** Most **NavigationServer3D** changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation-related nodes in the scene tree or made through scripts. For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than ``edge_connection_margin`` to the respective other edge's vertex. -You may assign navigation layers to regions with :ref:`region_set_navigation_layers`, which then can be checked upon when requesting a path with :ref:`map_get_path`. This allows allowing or forbidding some areas to 3D objects. +You may assign navigation layers to regions with :ref:`region_set_navigation_layers`, which then can be checked upon when requesting a path with :ref:`map_get_path`. This can be used to allow or deny certain areas for some objects. To use the collision avoidance system, you may use agents. You can set an agent's target velocity, then the servers will emit a callback with a modified velocity. -\ **Note:** The collision avoidance system ignores regions. Using the modified velocity as-is might lead to pushing and agent outside of a navigable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine. +\ **Note:** The collision avoidance system ignores regions. Using the modified velocity directly may move an agent outside of the traversable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine. This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying. diff --git a/classes/class_ninepatchrect.rst b/classes/class_ninepatchrect.rst index bf51022abf8..db396e1edab 100644 --- a/classes/class_ninepatchrect.rst +++ b/classes/class_ninepatchrect.rst @@ -12,14 +12,14 @@ NinePatchRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Scalable texture-based frame that tiles the texture's centers and sides, but keeps the corners' original size. Perfect for panels and dialog boxes. +A control that displays a texture by keeping its corners intact, but tiling its edges and center. .. rst-class:: classref-introduction-group Description ----------- -Also known as 9-slice panels, NinePatchRect produces clean panels of any size, based on a small texture. To do so, it splits the texture in a 3×3 grid. When you scale the node, it tiles the texture's sides horizontally or vertically, the center on both axes but it doesn't scale or tile the corners. +Also known as 9-slice panels, **NinePatchRect** produces clean panels of any size based on a small texture. To do so, it splits the texture in a 3×3 grid. When you scale the node, it tiles the texture's edges horizontally or vertically, tiles the center on both axes, and leaves the corners unchanged. .. rst-class:: classref-reftable-group diff --git a/classes/class_node.rst b/classes/class_node.rst index 968fa4ce328..c57837b9b16 100644 --- a/classes/class_node.rst +++ b/classes/class_node.rst @@ -14,7 +14,7 @@ Node **Inherited By:** :ref:`AnimationPlayer`, :ref:`AnimationTree`, :ref:`AudioStreamPlayer`, :ref:`CanvasItem`, :ref:`CanvasLayer`, :ref:`EditorFileSystem`, :ref:`EditorPlugin`, :ref:`EditorResourcePreview`, :ref:`HTTPRequest`, :ref:`InstancePlaceholder`, :ref:`MissingNode`, :ref:`MultiplayerSpawner`, :ref:`MultiplayerSynchronizer`, :ref:`NavigationAgent2D`, :ref:`NavigationAgent3D`, :ref:`Node3D`, :ref:`ResourcePreloader`, :ref:`ShaderGlobalsOverride`, :ref:`SkeletonIK3D`, :ref:`Timer`, :ref:`Viewport`, :ref:`WorldEnvironment` -Base class for all *scene* objects. +Base class for all scene objects. .. rst-class:: classref-introduction-group diff --git a/classes/class_nodepath.rst b/classes/class_nodepath.rst index 65d9e7fee7b..178935cd346 100644 --- a/classes/class_nodepath.rst +++ b/classes/class_nodepath.rst @@ -10,7 +10,7 @@ NodePath ======== -Pre-parsed scene tree path. +A pre-parsed scene tree path. .. rst-class:: classref-introduction-group @@ -42,6 +42,8 @@ See also :ref:`StringName`, which is a similar concept for gen \ **Note:** In the editor, **NodePath** properties are automatically updated when moving, renaming or deleting a node in the scene tree, but they are never updated at runtime. +\ **Note:** In a boolean context, a **NodePath** will evaluate to ``false`` if it is empty (``NodePath("")``). Otherwise, a **NodePath** will always evaluate to ``true``. + .. rst-class:: classref-introduction-group Tutorials diff --git a/classes/class_noisetexture2d.rst b/classes/class_noisetexture2d.rst index 46d072fd6fa..96b822d39a4 100644 --- a/classes/class_noisetexture2d.rst +++ b/classes/class_noisetexture2d.rst @@ -19,9 +19,7 @@ A texture filled with noise generated by a :ref:`Noise` object. Description ----------- -Uses :ref:`FastNoiseLite` or other libraries to fill the texture data of your desired size. - -NoiseTexture2D can also generate normalmap textures. +Uses :ref:`FastNoiseLite` or other libraries to fill the texture data of your desired size. **NoiseTexture2D** can also generate normal map textures. The class uses :ref:`Thread`\ s to generate the texture data internally, so :ref:`Texture2D.get_image` may return ``null`` if the generation process has not completed yet. In that case, you need to wait for the texture to be generated before accessing the image and the generated byte data: @@ -140,11 +138,9 @@ A :ref:`Gradient` which is used to map the luminance of each pix - void **set_generate_mipmaps** **(** :ref:`bool` value **)** - :ref:`bool` **is_generating_mipmaps** **(** **)** -Determines whether mipmaps are generated for this texture. - -Enabling this results in less texture aliasing, but the noise texture generation may take longer. +Determines whether mipmaps are generated for this texture. Enabling this results in less texture aliasing in the distance, at the cost of increasing memory usage by roughly 33% and making the noise texture generation take longer. -Requires (anisotropic) mipmap filtering to be enabled for a material to have an effect. +\ **Note:** :ref:`generate_mipmaps` requires mipmap filtering to be enabled on the material using the **NoiseTexture2D** to have an effect. .. rst-class:: classref-item-separator @@ -161,7 +157,7 @@ Requires (anisotropic) mipmap filtering to be enabled for a material to have an - void **set_height** **(** :ref:`int` value **)** - :ref:`int` **get_height** **(** **)** -Height of the generated texture. +Height of the generated texture (in pixels). .. rst-class:: classref-item-separator @@ -252,6 +248,8 @@ If ``true``, a seamless texture is requested from the :ref:`Noise` \ **Note:** Seamless noise textures may take longer to generate and/or can have a lower contrast compared to non-seamless noise depending on the used :ref:`Noise` resource. This is because some implementations use higher dimensions for generating seamless noise. +\ **Note:** The default :ref:`FastNoiseLite` implementation uses the fallback path for seamless generation. If using a :ref:`width` or :ref:`height` lower than the default, you may need to increase :ref:`seamless_blend_skirt` to make seamless blending more effective. + .. rst-class:: classref-item-separator ---- @@ -269,6 +267,8 @@ If ``true``, a seamless texture is requested from the :ref:`Noise` Used for the default/fallback implementation of the seamless texture generation. It determines the distance over which the seams are blended. High values may result in less details and contrast. See :ref:`Noise` for further details. +\ **Note:** If using a :ref:`width` or :ref:`height` lower than the default, you may need to increase :ref:`seamless_blend_skirt` to make seamless blending more effective. + .. rst-class:: classref-item-separator ---- @@ -284,7 +284,7 @@ Used for the default/fallback implementation of the seamless texture generation. - void **set_width** **(** :ref:`int` value **)** - :ref:`int` **get_width** **(** **)** -Width of the generated texture. +Width of the generated texture (in pixels). .. |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_noisetexture3d.rst b/classes/class_noisetexture3d.rst index 568a03919f1..ee6dd16257b 100644 --- a/classes/class_noisetexture3d.rst +++ b/classes/class_noisetexture3d.rst @@ -95,7 +95,7 @@ A :ref:`Gradient` which is used to map the luminance of each pix - void **set_depth** **(** :ref:`int` value **)** - :ref:`int` **get_depth** **(** **)** -Depth of the generated texture. +Depth of the generated texture (in pixels). .. rst-class:: classref-item-separator @@ -112,7 +112,7 @@ Depth of the generated texture. - void **set_height** **(** :ref:`int` value **)** - :ref:`int` **get_height** **(** **)** -Height of the generated texture. +Height of the generated texture (in pixels). .. rst-class:: classref-item-separator @@ -186,6 +186,8 @@ If ``true``, a seamless texture is requested from the :ref:`Noise` \ **Note:** Seamless noise textures may take longer to generate and/or can have a lower contrast compared to non-seamless noise depending on the used :ref:`Noise` resource. This is because some implementations use higher dimensions for generating seamless noise. +\ **Note:** The default :ref:`FastNoiseLite` implementation uses the fallback path for seamless generation. If using a :ref:`width`, :ref:`height` or :ref:`depth` lower than the default, you may need to increase :ref:`seamless_blend_skirt` to make seamless blending more effective. + .. rst-class:: classref-item-separator ---- @@ -203,6 +205,8 @@ If ``true``, a seamless texture is requested from the :ref:`Noise` Used for the default/fallback implementation of the seamless texture generation. It determines the distance over which the seams are blended. High values may result in less details and contrast. See :ref:`Noise` for further details. +\ **Note:** If using a :ref:`width`, :ref:`height` or :ref:`depth` lower than the default, you may need to increase :ref:`seamless_blend_skirt` to make seamless blending more effective. + .. rst-class:: classref-item-separator ---- @@ -218,7 +222,7 @@ Used for the default/fallback implementation of the seamless texture generation. - void **set_width** **(** :ref:`int` value **)** - :ref:`int` **get_width** **(** **)** -Width of the generated texture. +Width of the generated texture (in pixels). .. |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_object.rst b/classes/class_object.rst index af9abbf4e82..da02dd9bb48 100644 --- a/classes/class_object.rst +++ b/classes/class_object.rst @@ -1082,7 +1082,9 @@ Returns the object's unique instance ID. This ID can be saved in :ref:`EncodedOb Returns the object's metadata value for the given entry ``name``. If the entry does not exist, returns ``default``. If ``default`` is ``null``, an error is also generated. -\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector dock and should not be edited. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + +\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator @@ -1202,6 +1204,8 @@ Returns the list of existing signals as an :ref:`Array` of dictiona Returns ``true`` if a metadata entry is found with the given ``name``. See also :ref:`get_meta`, :ref:`set_meta` and :ref:`remove_meta`. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + \ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator @@ -1408,7 +1412,9 @@ void **remove_meta** **(** :ref:`StringName` name **)** Removes the given entry ``name`` from the object's metadata. See also :ref:`has_meta`, :ref:`get_meta` and :ref:`set_meta`. -\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + +\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator @@ -1553,7 +1559,9 @@ Adds or changes the entry ``name`` inside the object's metadata. The metadata `` If ``value`` is ``null``, the entry is removed. This is the equivalent of using :ref:`remove_meta`. See also :ref:`has_meta` and :ref:`get_meta`. -\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector dock and should not be edited. +\ **Note:** A metadata's ``name`` must be a valid identifier as per :ref:`StringName.is_valid_identifier` method. + +\ **Note:** Metadata that has a ``name`` starting with an underscore (``_``) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. .. rst-class:: classref-item-separator diff --git a/classes/class_optimizedtranslation.rst b/classes/class_optimizedtranslation.rst index 9d7b87ad5a9..2de54cabe47 100644 --- a/classes/class_optimizedtranslation.rst +++ b/classes/class_optimizedtranslation.rst @@ -12,14 +12,14 @@ OptimizedTranslation **Inherits:** :ref:`Translation` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Optimized translation. +An optimized translation, used by default for CSV Translations. .. rst-class:: classref-introduction-group Description ----------- -Optimized translation. Uses real-time compressed translations, which results in very small dictionaries. +An optimized translation, used by default for CSV Translations. Uses real-time compressed translations, which results in very small dictionaries. .. rst-class:: classref-reftable-group diff --git a/classes/class_optionbutton.rst b/classes/class_optionbutton.rst index ee64e5cfa20..8dd644c647f 100644 --- a/classes/class_optionbutton.rst +++ b/classes/class_optionbutton.rst @@ -12,14 +12,14 @@ OptionButton **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Button control that provides selectable options when pressed. +A button that brings up a dropdown with selectable options when pressed. .. rst-class:: classref-introduction-group Description ----------- -OptionButton is a type button that provides a selectable list of items when pressed. The item selected becomes the "current" item and is displayed as the button text. +**OptionButton** is a type of button that brings up a dropdown with selectable items when pressed. The item selected becomes the "current" item and is displayed as the button text. See also :ref:`BaseButton` which contains common properties and methods associated with this node. @@ -27,6 +27,10 @@ See also :ref:`BaseButton` which contains common properties an \ **Note:** The ID values used for items are limited to 32 bits, not full 64 bits of :ref:`int`. This has a range of ``-2^32`` to ``2^32 - 1``, i.e. ``-2147483648`` to ``2147483647``. +\ **Note:** The ID values used for items are 32-bit, unlike :ref:`int` which is always 64-bit. They go from ``-2147483648`` to ``2147483647``. + +\ **Note:** The :ref:`Button.text` and :ref:`Button.icon` properties are set automatically based on the selected item. They shouldn't be changed manually. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_os.rst b/classes/class_os.rst index fed61bc5267..b65d96a6aee 100644 --- a/classes/class_os.rst +++ b/classes/class_os.rst @@ -12,14 +12,14 @@ OS **Inherits:** :ref:`Object` -Operating System functions. +Provides access to common operating system functionalities. .. rst-class:: classref-introduction-group Description ----------- -Operating System functions. **OS** wraps the most common functionality to communicate with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. +This class wraps the most common functionalities for communicating with the host operating system, such as the video driver, delays, environment variables, execution of binaries, command line, etc. \ **Note:** In Godot 4, **OS** functions related to window management were moved to the :ref:`DisplayServer` singleton. @@ -736,7 +736,7 @@ Returns the path to the current engine executable. With this function, you can get the list of dangerous permissions that have been granted to the Android application. -\ **Note:** This method is implemented on Android. +\ **Note:** This method is implemented only on Android. .. rst-class:: classref-item-separator @@ -1365,7 +1365,7 @@ At the moment this function is only used by ``AudioDriverOpenSL`` to request per With this function, you can request dangerous permissions since normal permissions are automatically granted at install time in Android applications. -\ **Note:** This method is implemented on Android. +\ **Note:** This method is implemented only on Android. .. rst-class:: classref-item-separator diff --git a/classes/class_packeddatacontainerref.rst b/classes/class_packeddatacontainerref.rst index 9775322329a..98006a26a6d 100644 --- a/classes/class_packeddatacontainerref.rst +++ b/classes/class_packeddatacontainerref.rst @@ -12,7 +12,7 @@ PackedDataContainerRef **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Internal class used by :ref:`PackedDataContainer`. +An internal class used by :ref:`PackedDataContainer` to pack nested arrays and dictionaries. .. rst-class:: classref-introduction-group diff --git a/classes/class_packedfloat32array.rst b/classes/class_packedfloat32array.rst index 94a276d8091..8a8a0632920 100644 --- a/classes/class_packedfloat32array.rst +++ b/classes/class_packedfloat32array.rst @@ -187,6 +187,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -211,6 +213,8 @@ Clears the array. This is equivalent to using :ref:`resize` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -247,6 +251,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -259,6 +265,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -343,6 +351,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -395,6 +405,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_packedfloat64array.rst b/classes/class_packedfloat64array.rst index 36ee060d75b..c664b6326e8 100644 --- a/classes/class_packedfloat64array.rst +++ b/classes/class_packedfloat64array.rst @@ -187,6 +187,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -211,6 +213,8 @@ Clears the array. This is equivalent to using :ref:`resize` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -247,6 +251,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -259,6 +265,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -343,6 +351,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -395,6 +405,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** :ref:`@GDScript.NAN` doesn't behave the same as other numbers. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_packedvector2array.rst b/classes/class_packedvector2array.rst index 6ce6d0908a7..6e1a97932af 100644 --- a/classes/class_packedvector2array.rst +++ b/classes/class_packedvector2array.rst @@ -194,6 +194,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -218,6 +220,8 @@ Clears the array. This is equivalent to using :ref:`resize` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -254,6 +258,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -266,6 +272,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -350,6 +358,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -402,6 +412,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_packedvector3array.rst b/classes/class_packedvector3array.rst index d51d69160da..e3831baade7 100644 --- a/classes/class_packedvector3array.rst +++ b/classes/class_packedvector3array.rst @@ -187,6 +187,8 @@ Finds the index of an existing value (or the insertion index that maintains sort \ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -211,6 +213,8 @@ Clears the array. This is equivalent to using :ref:`resize` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -247,6 +251,8 @@ Assigns the given value to all elements in the array. This can typically be used Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -259,6 +265,8 @@ Searches the array for a value and returns its index or ``-1`` if not found. Opt Returns ``true`` if the array contains ``value``. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -343,6 +351,8 @@ Reverses the order of the elements in the array. Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -395,6 +405,8 @@ void **sort** **(** **)** Sorts the elements of the array in ascending order. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this method may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_panel.rst b/classes/class_panel.rst index 9525e0497bf..6e3a4eed7e2 100644 --- a/classes/class_panel.rst +++ b/classes/class_panel.rst @@ -12,14 +12,14 @@ Panel **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Provides an opaque background for :ref:`Control` children. +A GUI control that displays a :ref:`StyleBox`. .. rst-class:: classref-introduction-group Description ----------- -Panel is a :ref:`Control` that displays an opaque background. It's commonly used as a parent and container for other types of :ref:`Control` nodes. +**Panel** is a GUI control that displays a :ref:`StyleBox`. See also :ref:`PanelContainer`. .. rst-class:: classref-introduction-group @@ -59,7 +59,7 @@ Theme Property Descriptions :ref:`StyleBox` **panel** -The style of this **Panel**. +The :ref:`StyleBox` of this control. .. |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_panelcontainer.rst b/classes/class_panelcontainer.rst index 68f7f41062a..7580d849784 100644 --- a/classes/class_panelcontainer.rst +++ b/classes/class_panelcontainer.rst @@ -14,21 +14,21 @@ PanelContainer **Inherited By:** :ref:`ScriptEditor` -Panel container type. +A container that keeps its child controls within the area of a :ref:`StyleBox`. .. rst-class:: classref-introduction-group Description ----------- -Panel container type. This container fits controls inside of the delimited area of a stylebox. It's useful for giving controls an outline. +A container that keeps its child controls within the area of a :ref:`StyleBox`. Useful for giving controls an outline. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` - `2D Role Playing Game Demo `__ diff --git a/classes/class_parallaxbackground.rst b/classes/class_parallaxbackground.rst index 8094a7fbeef..c248ae9fb32 100644 --- a/classes/class_parallaxbackground.rst +++ b/classes/class_parallaxbackground.rst @@ -21,6 +21,8 @@ Description A ParallaxBackground uses one or more :ref:`ParallaxLayer` child nodes to create a parallax effect. Each :ref:`ParallaxLayer` can move at a different speed using :ref:`ParallaxLayer.motion_offset`. This creates an illusion of depth in a 2D game. If not used with a :ref:`Camera2D`, you must manually calculate the :ref:`scroll_offset`. +\ **Note:** Each **ParallaxBackground** is drawn on one specific :ref:`Viewport` and cannot be shared between multiple :ref:`Viewport`\ s, see :ref:`CanvasLayer.custom_viewport`. When using multiple :ref:`Viewport`\ s, for example in a split-screen game, you need create an individual **ParallaxBackground** for each :ref:`Viewport` you want it to be drawn on. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_physicsbody2d.rst b/classes/class_physicsbody2d.rst index b6e4ebd058a..672ab638a84 100644 --- a/classes/class_physicsbody2d.rst +++ b/classes/class_physicsbody2d.rst @@ -14,14 +14,14 @@ PhysicsBody2D **Inherited By:** :ref:`CharacterBody2D`, :ref:`RigidBody2D`, :ref:`StaticBody2D` -Base class for all objects affected by physics in 2D space. +Abstract base class for 2D game objects affected by physics. .. rst-class:: classref-introduction-group Description ----------- -PhysicsBody2D is an abstract base class for implementing a physics body. All \*Body2D types inherit from it. +**PhysicsBody2D** is an abstract base class for 2D game objects affected by physics. All 2D physics bodies inherit from it. .. rst-class:: classref-introduction-group diff --git a/classes/class_physicsbody3d.rst b/classes/class_physicsbody3d.rst index 4329ecfdd00..ddabb7c157c 100644 --- a/classes/class_physicsbody3d.rst +++ b/classes/class_physicsbody3d.rst @@ -14,16 +14,16 @@ PhysicsBody3D **Inherited By:** :ref:`CharacterBody3D`, :ref:`PhysicalBone3D`, :ref:`RigidBody3D`, :ref:`StaticBody3D` -Base class for all objects affected by physics in 3D space. +Abstract base class for 3D game objects affected by physics. .. rst-class:: classref-introduction-group Description ----------- -PhysicsBody3D is an abstract base class for implementing a physics body. All \*Body3D types inherit from it. +**PhysicsBody3D** is an abstract base class for 3D game objects affected by physics. All 3D physics bodies inherit from it. -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +\ **Warning:** With a non-uniform scale, this node will likely not behave as expected. It is advised to keep its scale the same on all axes and adjust its collision shape(s) instead. .. rst-class:: classref-introduction-group diff --git a/classes/class_physicsdirectbodystate2d.rst b/classes/class_physicsdirectbodystate2d.rst index 61709111e90..fe8d243c35a 100644 --- a/classes/class_physicsdirectbodystate2d.rst +++ b/classes/class_physicsdirectbodystate2d.rst @@ -14,14 +14,14 @@ PhysicsDirectBodyState2D **Inherited By:** :ref:`PhysicsDirectBodyState2DExtension` -Direct access object to a physics body in the :ref:`PhysicsServer2D`. +Provides direct access to a physics body in the :ref:`PhysicsServer2D`. .. rst-class:: classref-introduction-group Description ----------- -Provides direct access to a physics body in the :ref:`PhysicsServer2D`, allowing safe changes to physics properties. This object is passed via the direct state callback of rigid bodies, and is intended for changing the direct state of that body. See :ref:`RigidBody2D._integrate_forces`. +Provides direct access to a physics body in the :ref:`PhysicsServer2D`, allowing safe changes to physics properties. This object is passed via the direct state callback of :ref:`RigidBody2D`, and is intended for changing the direct state of that body. See :ref:`RigidBody2D._integrate_forces`. .. rst-class:: classref-introduction-group diff --git a/classes/class_physicsdirectbodystate2dextension.rst b/classes/class_physicsdirectbodystate2dextension.rst index 40f8571a580..ed9bc5a27e4 100644 --- a/classes/class_physicsdirectbodystate2dextension.rst +++ b/classes/class_physicsdirectbodystate2dextension.rst @@ -12,9 +12,16 @@ PhysicsDirectBodyState2DExtension **Inherits:** :ref:`PhysicsDirectBodyState2D` **<** :ref:`Object` -.. container:: contribute +Provides virtual methods that can be overridden to create custom :ref:`PhysicsDirectBodyState2D` implementations. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class extends :ref:`PhysicsDirectBodyState2D` by providing additional virtual methods that can be overridden. When these methods are overridden, they will be called instead of the internal methods of the physics server. - There is currently no description for this class. Please help us by :ref:`contributing one `! +Intended for use with GDExtension to create custom implementations of :ref:`PhysicsDirectBodyState2D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsdirectbodystate3d.rst b/classes/class_physicsdirectbodystate3d.rst index bb75af98175..6b5461634df 100644 --- a/classes/class_physicsdirectbodystate3d.rst +++ b/classes/class_physicsdirectbodystate3d.rst @@ -14,14 +14,14 @@ PhysicsDirectBodyState3D **Inherited By:** :ref:`PhysicsDirectBodyState3DExtension` -Direct access object to a physics body in the :ref:`PhysicsServer3D`. +Provides direct access to a physics body in the :ref:`PhysicsServer3D`. .. rst-class:: classref-introduction-group Description ----------- -Provides direct access to a physics body in the :ref:`PhysicsServer3D`, allowing safe changes to physics properties. This object is passed via the direct state callback of rigid bodies, and is intended for changing the direct state of that body. See :ref:`RigidBody3D._integrate_forces`. +Provides direct access to a physics body in the :ref:`PhysicsServer3D`, allowing safe changes to physics properties. This object is passed via the direct state callback of :ref:`RigidBody3D`, and is intended for changing the direct state of that body. See :ref:`RigidBody3D._integrate_forces`. .. rst-class:: classref-introduction-group diff --git a/classes/class_physicsdirectbodystate3dextension.rst b/classes/class_physicsdirectbodystate3dextension.rst index 3f79037ea7c..6ae9124514a 100644 --- a/classes/class_physicsdirectbodystate3dextension.rst +++ b/classes/class_physicsdirectbodystate3dextension.rst @@ -12,9 +12,16 @@ PhysicsDirectBodyState3DExtension **Inherits:** :ref:`PhysicsDirectBodyState3D` **<** :ref:`Object` -.. container:: contribute +Provides virtual methods that can be overridden to create custom :ref:`PhysicsDirectBodyState3D` implementations. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class extends :ref:`PhysicsDirectBodyState3D` by providing additional virtual methods that can be overridden. When these methods are overridden, they will be called instead of the internal methods of the physics server. - There is currently no description for this class. Please help us by :ref:`contributing one `! +Intended for use with GDExtension to create custom implementations of :ref:`PhysicsDirectBodyState3D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsdirectspacestate2d.rst b/classes/class_physicsdirectspacestate2d.rst index 06900c82ab7..103369bf73c 100644 --- a/classes/class_physicsdirectspacestate2d.rst +++ b/classes/class_physicsdirectspacestate2d.rst @@ -14,14 +14,14 @@ PhysicsDirectSpaceState2D **Inherited By:** :ref:`PhysicsDirectSpaceState2DExtension` -Direct access object to a space in the :ref:`PhysicsServer2D`. +Provides direct access to a physics space in the :ref:`PhysicsServer2D`. .. rst-class:: classref-introduction-group Description ----------- -Direct access object to a space in the :ref:`PhysicsServer2D`. It's used mainly to do queries against objects and areas residing in a given space. +Provides direct access to a physics space in the :ref:`PhysicsServer2D`. It's used mainly to do queries against objects and areas residing in a given space. .. rst-class:: classref-introduction-group diff --git a/classes/class_physicsdirectspacestate2dextension.rst b/classes/class_physicsdirectspacestate2dextension.rst index 5c9cdbce89d..475dd506069 100644 --- a/classes/class_physicsdirectspacestate2dextension.rst +++ b/classes/class_physicsdirectspacestate2dextension.rst @@ -12,9 +12,16 @@ PhysicsDirectSpaceState2DExtension **Inherits:** :ref:`PhysicsDirectSpaceState2D` **<** :ref:`Object` -.. container:: contribute +Provides virtual methods that can be overridden to create custom :ref:`PhysicsDirectSpaceState2D` implementations. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class extends :ref:`PhysicsDirectSpaceState2D` by providing additional virtual methods that can be overridden. When these methods are overridden, they will be called instead of the internal methods of the physics server. - There is currently no description for this class. Please help us by :ref:`contributing one `! +Intended for use with GDExtension to create custom implementations of :ref:`PhysicsDirectSpaceState2D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsdirectspacestate3d.rst b/classes/class_physicsdirectspacestate3d.rst index 4b52ab791e4..93441440485 100644 --- a/classes/class_physicsdirectspacestate3d.rst +++ b/classes/class_physicsdirectspacestate3d.rst @@ -14,14 +14,14 @@ PhysicsDirectSpaceState3D **Inherited By:** :ref:`PhysicsDirectSpaceState3DExtension` -Direct access object to a space in the :ref:`PhysicsServer3D`. +Provides direct access to a physics space in the :ref:`PhysicsServer3D`. .. rst-class:: classref-introduction-group Description ----------- -Direct access object to a space in the :ref:`PhysicsServer3D`. It's used mainly to do queries against objects and areas residing in a given space. +Provides direct access to a physics space in the :ref:`PhysicsServer3D`. It's used mainly to do queries against objects and areas residing in a given space. .. rst-class:: classref-introduction-group diff --git a/classes/class_physicsdirectspacestate3dextension.rst b/classes/class_physicsdirectspacestate3dextension.rst index edb1614d425..798809f1c62 100644 --- a/classes/class_physicsdirectspacestate3dextension.rst +++ b/classes/class_physicsdirectspacestate3dextension.rst @@ -12,9 +12,16 @@ PhysicsDirectSpaceState3DExtension **Inherits:** :ref:`PhysicsDirectSpaceState3D` **<** :ref:`Object` -.. container:: contribute +Provides virtual methods that can be overridden to create custom :ref:`PhysicsDirectSpaceState3D` implementations. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class extends :ref:`PhysicsDirectSpaceState3D` by providing additional virtual methods that can be overridden. When these methods are overridden, they will be called instead of the internal methods of the physics server. - There is currently no description for this class. Please help us by :ref:`contributing one `! +Intended for use with GDExtension to create custom implementations of :ref:`PhysicsDirectSpaceState3D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsmaterial.rst b/classes/class_physicsmaterial.rst index 969224b307f..6aa9551634e 100644 --- a/classes/class_physicsmaterial.rst +++ b/classes/class_physicsmaterial.rst @@ -12,14 +12,14 @@ PhysicsMaterial **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A material for physics properties. +Holds physics-related properties of a surface, namely its roughness and bounciness. .. rst-class:: classref-introduction-group Description ----------- -Provides a means of modifying the collision properties of a :ref:`PhysicsBody3D`. +Holds physics-related properties of a surface, namely its roughness and bounciness. This class is used to apply these properties to a physics body. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicspointqueryparameters2d.rst b/classes/class_physicspointqueryparameters2d.rst index 20e1608997e..bfacaeb13e5 100644 --- a/classes/class_physicspointqueryparameters2d.rst +++ b/classes/class_physicspointqueryparameters2d.rst @@ -12,14 +12,14 @@ PhysicsPointQueryParameters2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 2D point physics query. +Provides parameters for :ref:`PhysicsDirectSpaceState2D.intersect_point`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the position and other parameters to be used for :ref:`PhysicsDirectSpaceState2D.intersect_point`. +By changing various properties of this object, such as the point position, you can configure the parameters for :ref:`PhysicsDirectSpaceState2D.intersect_point`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicspointqueryparameters3d.rst b/classes/class_physicspointqueryparameters3d.rst index d895d3424f1..9f13435133b 100644 --- a/classes/class_physicspointqueryparameters3d.rst +++ b/classes/class_physicspointqueryparameters3d.rst @@ -12,14 +12,14 @@ PhysicsPointQueryParameters3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 3D point physics query. +Provides parameters for :ref:`PhysicsDirectSpaceState3D.intersect_point`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the position and other parameters to be used for :ref:`PhysicsDirectSpaceState3D.intersect_point`. +By changing various properties of this object, such as the point position, you can configure the parameters for :ref:`PhysicsDirectSpaceState3D.intersect_point`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsrayqueryparameters2d.rst b/classes/class_physicsrayqueryparameters2d.rst index 9e3c2402bc0..d4e51be2481 100644 --- a/classes/class_physicsrayqueryparameters2d.rst +++ b/classes/class_physicsrayqueryparameters2d.rst @@ -12,14 +12,14 @@ PhysicsRayQueryParameters2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 2D ray physics query. +Provides parameters for :ref:`PhysicsDirectSpaceState2D.intersect_ray`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the ray position and other parameters to be used for :ref:`PhysicsDirectSpaceState2D.intersect_ray`. +By changing various properties of this object, such as the ray position, you can configure the parameters for :ref:`PhysicsDirectSpaceState2D.intersect_ray`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsrayqueryparameters3d.rst b/classes/class_physicsrayqueryparameters3d.rst index d7ce447427f..eeb39440ecd 100644 --- a/classes/class_physicsrayqueryparameters3d.rst +++ b/classes/class_physicsrayqueryparameters3d.rst @@ -12,14 +12,14 @@ PhysicsRayQueryParameters3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 3D ray physics query. +Provides parameters for :ref:`PhysicsDirectSpaceState3D.intersect_ray`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the ray position and other parameters to be used for :ref:`PhysicsDirectSpaceState3D.intersect_ray`. +By changing various properties of this object, such as the ray position, you can configure the parameters for :ref:`PhysicsDirectSpaceState3D.intersect_ray`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsserver2d.rst b/classes/class_physicsserver2d.rst index 34804ead399..0f06b386a97 100644 --- a/classes/class_physicsserver2d.rst +++ b/classes/class_physicsserver2d.rst @@ -14,7 +14,7 @@ PhysicsServer2D **Inherited By:** :ref:`PhysicsServer2DExtension` -Server interface for low-level 2D physics access. +A server interface for low-level 2D physics access. .. rst-class:: classref-introduction-group @@ -25,7 +25,7 @@ PhysicsServer2D is the server responsible for all 2D physics. It can directly cr - A *space* is a self-contained world for a physics simulation. It contains bodies, areas, and joints. Its state can be queried for collision and intersection information, and several parameters of the simulation can be modified. -- A *shape* is a geometric figure such as a circle, a rectangle, a capsule, or a polygon. It can be used for collision detection by adding it to a body/area, possibly with an extra transformation relative to the body/area's origin. Bodies/areas can have multiple (transformed) shapes added to them, and a single shape can be added to bodies/areas multiple times with different local transformations. +- A *shape* is a geometric shape such as a circle, a rectangle, a capsule, or a polygon. It can be used for collision detection by adding it to a body/area, possibly with an extra transformation relative to the body/area's origin. Bodies/areas can have multiple (transformed) shapes added to them, and a single shape can be added to bodies/areas multiple times with different local transformations. - A *body* is a physical object which can be in static, kinematic, or rigid mode. Its state (such as position and velocity) can be queried and updated. A force integration callback can be set to customize the body's physics. @@ -33,9 +33,9 @@ PhysicsServer2D is the server responsible for all 2D physics. It can directly cr - A *joint* is a constraint, either between two bodies or on one body relative to a point. Parameters such as the joint bias and the rest length of a spring joint can be adjusted. -Physics objects in the physics server may be created and manipulated independently; they do not have to be tied to nodes in the scene tree. +Physics objects in **PhysicsServer2D** may be created and manipulated independently; they do not have to be tied to nodes in the scene tree. -\ **Note:** All the physics nodes use the physics server internally. Adding a physics node to the scene tree will cause a corresponding physics object to be created in the physics server. A rigid body node registers a callback that updates the node's transform with the transform of the respective body object in the physics server (every physics update). An area node registers a callback to inform the area node about overlaps with the respective area object in the physics server. The raycast node queries the direct state of the relevant space in the physics server. +\ **Note:** All the 2D physics nodes use the physics server internally. Adding a physics node to the scene tree will cause a corresponding physics object to be created in the physics server. A rigid body node registers a callback that updates the node's transform with the transform of the respective body object in the physics server (every physics update). An area node registers a callback to inform the area node about overlaps with the respective area object in the physics server. The raycast node queries the direct state of the relevant space in the physics server. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsserver2dextension.rst b/classes/class_physicsserver2dextension.rst index 2aecdc86b83..75b4395386f 100644 --- a/classes/class_physicsserver2dextension.rst +++ b/classes/class_physicsserver2dextension.rst @@ -12,9 +12,16 @@ PhysicsServer2DExtension **Inherits:** :ref:`PhysicsServer2D` **<** :ref:`Object` -.. container:: contribute +Provides virtual methods that can be overridden to create custom :ref:`PhysicsServer2D` implementations. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class extends :ref:`PhysicsServer2D` by providing additional virtual methods that can be overridden. When these methods are overridden, they will be called instead of the internal methods of the physics server. - There is currently no description for this class. Please help us by :ref:`contributing one `! +Intended for use with GDExtension to create custom implementations of :ref:`PhysicsServer2D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsserver2dmanager.rst b/classes/class_physicsserver2dmanager.rst index 7586385fc29..1db96542584 100644 --- a/classes/class_physicsserver2dmanager.rst +++ b/classes/class_physicsserver2dmanager.rst @@ -12,14 +12,14 @@ PhysicsServer2DManager **Inherits:** :ref:`Object` -Manager for 2D physics server implementations. +A singleton for managing :ref:`PhysicsServer2D` implementations. .. rst-class:: classref-introduction-group Description ----------- -**PhysicsServer2DManager** is the API for registering :ref:`PhysicsServer2D` implementations, and for setting the default implementation. +**PhysicsServer2DManager** is the API for registering :ref:`PhysicsServer2D` implementations and for setting the default implementation. \ **Note:** It is not possible to switch physics servers at runtime. This class is only used on startup at the server initialization level, by Godot itself and possibly by GDExtensions. diff --git a/classes/class_physicsserver3d.rst b/classes/class_physicsserver3d.rst index 9e0f5141c87..a485a09f0b6 100644 --- a/classes/class_physicsserver3d.rst +++ b/classes/class_physicsserver3d.rst @@ -14,14 +14,28 @@ PhysicsServer3D **Inherited By:** :ref:`PhysicsServer3DExtension` -Server interface for low-level physics access. +A server interface for low-level 3D physics access. .. rst-class:: classref-introduction-group Description ----------- -PhysicsServer3D is the server responsible for all 3D physics. It can create many kinds of physics objects, but does not insert them on the node tree. +PhysicsServer2D is the server responsible for all 2D physics. It can directly create and manipulate all physics objects: + +- A *space* is a self-contained world for a physics simulation. It contains bodies, areas, and joints. Its state can be queried for collision and intersection information, and several parameters of the simulation can be modified. + +- A *shape* is a geometric shape such as a sphere, a box, a cylinder, or a polygon. It can be used for collision detection by adding it to a body/area, possibly with an extra transformation relative to the body/area's origin. Bodies/areas can have multiple (transformed) shapes added to them, and a single shape can be added to bodies/areas multiple times with different local transformations. + +- A *body* is a physical object which can be in static, kinematic, or rigid mode. Its state (such as position and velocity) can be queried and updated. A force integration callback can be set to customize the body's physics. + +- An *area* is a region in space which can be used to detect bodies and areas entering and exiting it. A body monitoring callback can be set to report entering/exiting body shapes, and similarly an area monitoring callback can be set. Gravity and damping can be overridden within the area by setting area parameters. + +- A *joint* is a constraint, either between two bodies or on one body relative to a point. Parameters such as the joint bias and the rest length of a spring joint can be adjusted. + +Physics objects in **PhysicsServer3D** may be created and manipulated independently; they do not have to be tied to nodes in the scene tree. + +\ **Note:** All the 3D physics nodes use the physics server internally. Adding a physics node to the scene tree will cause a corresponding physics object to be created in the physics server. A rigid body node registers a callback that updates the node's transform with the transform of the respective body object in the physics server (every physics update). An area node registers a callback to inform the area node about overlaps with the respective area object in the physics server. The raycast node queries the direct state of the relevant space in the physics server. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsserver3dextension.rst b/classes/class_physicsserver3dextension.rst index c0fb05fa286..0b4858d87a2 100644 --- a/classes/class_physicsserver3dextension.rst +++ b/classes/class_physicsserver3dextension.rst @@ -12,9 +12,16 @@ PhysicsServer3DExtension **Inherits:** :ref:`PhysicsServer3D` **<** :ref:`Object` -.. container:: contribute +Provides virtual methods that can be overridden to create custom :ref:`PhysicsServer3D` implementations. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This class extends :ref:`PhysicsServer3D` by providing additional virtual methods that can be overridden. When these methods are overridden, they will be called instead of the internal methods of the physics server. - There is currently no description for this class. Please help us by :ref:`contributing one `! +Intended for use with GDExtension to create custom implementations of :ref:`PhysicsServer3D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsserver3dmanager.rst b/classes/class_physicsserver3dmanager.rst index 93b20cf7fb6..545377364c2 100644 --- a/classes/class_physicsserver3dmanager.rst +++ b/classes/class_physicsserver3dmanager.rst @@ -12,14 +12,14 @@ PhysicsServer3DManager **Inherits:** :ref:`Object` -Manager for 3D physics server implementations. +A singleton for managing :ref:`PhysicsServer3D` implementations. .. rst-class:: classref-introduction-group Description ----------- -**PhysicsServer3DManager** is the API for registering :ref:`PhysicsServer3D` implementations, and for setting the default implementation. +**PhysicsServer3DManager** is the API for registering :ref:`PhysicsServer3D` implementations and for setting the default implementation. \ **Note:** It is not possible to switch physics servers at runtime. This class is only used on startup at the server initialization level, by Godot itself and possibly by GDExtensions. diff --git a/classes/class_physicsserver3drenderingserverhandler.rst b/classes/class_physicsserver3drenderingserverhandler.rst index fd2b278b32c..c054d1dccff 100644 --- a/classes/class_physicsserver3drenderingserverhandler.rst +++ b/classes/class_physicsserver3drenderingserverhandler.rst @@ -12,9 +12,7 @@ PhysicsServer3DRenderingServerHandler **Inherits:** :ref:`Object` -.. container:: contribute - - There is currently no description for this class. Please help us by :ref:`contributing one `! +A class used to provide :ref:`PhysicsServer3DExtension._soft_body_update_rendering_server` with a rendering handler for soft bodies. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsshapequeryparameters2d.rst b/classes/class_physicsshapequeryparameters2d.rst index 3d7646466f1..49f820aa96a 100644 --- a/classes/class_physicsshapequeryparameters2d.rst +++ b/classes/class_physicsshapequeryparameters2d.rst @@ -12,14 +12,14 @@ PhysicsShapeQueryParameters2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 2D shape physics query. +Provides parameters for :ref:`PhysicsDirectSpaceState2D.intersect_shape`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the shape and other parameters for :ref:`PhysicsDirectSpaceState2D` intersection/collision queries. +By changing various properties of this object, such as the shape, you can configure the parameters for :ref:`PhysicsDirectSpaceState2D.intersect_shape`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicsshapequeryparameters3d.rst b/classes/class_physicsshapequeryparameters3d.rst index 630338ecd67..d940f8ac551 100644 --- a/classes/class_physicsshapequeryparameters3d.rst +++ b/classes/class_physicsshapequeryparameters3d.rst @@ -12,14 +12,14 @@ PhysicsShapeQueryParameters3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 3D shape physics query. +Provides parameters for :ref:`PhysicsDirectSpaceState3D.intersect_shape`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the shape and other parameters for :ref:`PhysicsDirectSpaceState3D` intersection/collision queries. +By changing various properties of this object, such as the shape, you can configure the parameters for :ref:`PhysicsDirectSpaceState3D.intersect_shape`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicstestmotionparameters2d.rst b/classes/class_physicstestmotionparameters2d.rst index 055c9844446..c1470dcff43 100644 --- a/classes/class_physicstestmotionparameters2d.rst +++ b/classes/class_physicstestmotionparameters2d.rst @@ -12,14 +12,14 @@ PhysicsTestMotionParameters2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 2D body motion test. +Provides parameters for :ref:`PhysicsServer2D.body_test_motion`. .. rst-class:: classref-introduction-group Description ----------- -This class contains parameters used in :ref:`PhysicsServer2D.body_test_motion`. +By changing various properties of this object, such as the motion, you can configure the parameters for :ref:`PhysicsServer2D.body_test_motion`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicstestmotionparameters3d.rst b/classes/class_physicstestmotionparameters3d.rst index 571d898b123..b19e7c64c5a 100644 --- a/classes/class_physicstestmotionparameters3d.rst +++ b/classes/class_physicstestmotionparameters3d.rst @@ -12,14 +12,14 @@ PhysicsTestMotionParameters3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Parameters to be sent to a 3D body motion test. +Provides parameters for :ref:`PhysicsServer3D.body_test_motion`. .. rst-class:: classref-introduction-group Description ----------- -This class contains parameters used in :ref:`PhysicsServer3D.body_test_motion`. +By changing various properties of this object, such as the motion, you can configure the parameters for :ref:`PhysicsServer3D.body_test_motion`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicstestmotionresult2d.rst b/classes/class_physicstestmotionresult2d.rst index 9571f339f3a..ac70482497c 100644 --- a/classes/class_physicstestmotionresult2d.rst +++ b/classes/class_physicstestmotionresult2d.rst @@ -12,14 +12,14 @@ PhysicsTestMotionResult2D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Result from a 2D body motion test. +Describes the motion and collision result from :ref:`PhysicsServer2D.body_test_motion`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the motion and collision result from :ref:`PhysicsServer2D.body_test_motion`. +Describes the motion and collision result from :ref:`PhysicsServer2D.body_test_motion`. .. rst-class:: classref-reftable-group diff --git a/classes/class_physicstestmotionresult3d.rst b/classes/class_physicstestmotionresult3d.rst index 6e30efd1816..37d1d069a7f 100644 --- a/classes/class_physicstestmotionresult3d.rst +++ b/classes/class_physicstestmotionresult3d.rst @@ -12,14 +12,14 @@ PhysicsTestMotionResult3D **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Result from a 3D body motion test. +Describes the motion and collision result from :ref:`PhysicsServer3D.body_test_motion`. .. rst-class:: classref-introduction-group Description ----------- -This class contains the motion and collision result from :ref:`PhysicsServer3D.body_test_motion`. +Describes the motion and collision result from :ref:`PhysicsServer3D.body_test_motion`. .. rst-class:: classref-reftable-group diff --git a/classes/class_pinjoint2d.rst b/classes/class_pinjoint2d.rst index 8166dda49d6..bcb84da9c25 100644 --- a/classes/class_pinjoint2d.rst +++ b/classes/class_pinjoint2d.rst @@ -12,14 +12,14 @@ PinJoint2D **Inherits:** :ref:`Joint2D` **<** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Pin joint for 2D shapes. +A physics joint that attaches two 2D physics bodies at a single point, allowing them to freely rotate. .. rst-class:: classref-introduction-group Description ----------- -Pin joint for 2D rigid bodies. It pins two bodies (dynamic or static) together. +A physics joint that attaches two 2D physics bodies at a single point, allowing them to freely rotate. For example, a :ref:`RigidBody2D` can be attached to a :ref:`StaticBody2D` to create a pendulum or a seesaw. .. rst-class:: classref-reftable-group diff --git a/classes/class_pinjoint3d.rst b/classes/class_pinjoint3d.rst index b831402d806..cf8fee45471 100644 --- a/classes/class_pinjoint3d.rst +++ b/classes/class_pinjoint3d.rst @@ -12,14 +12,14 @@ PinJoint3D **Inherits:** :ref:`Joint3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Pin joint for 3D PhysicsBodies. +A physics joint that attaches two 3D physics bodies at a single point, allowing them to freely rotate. .. rst-class:: classref-introduction-group Description ----------- -Pin joint for 3D rigid bodies. It pins 2 bodies (dynamic or static) together. See also :ref:`Generic6DOFJoint3D`. +A physics joint that attaches two 2D physics bodies at a single point, allowing them to freely rotate. For example, a :ref:`RigidBody3D` can be attached to a :ref:`StaticBody3D` to create a pendulum or a seesaw. .. rst-class:: classref-reftable-group diff --git a/classes/class_plane.rst b/classes/class_plane.rst index e5130f70531..c06c8896432 100644 --- a/classes/class_plane.rst +++ b/classes/class_plane.rst @@ -10,14 +10,14 @@ Plane ===== -Plane in hessian form. +A plane in Hessian normal form. .. rst-class:: classref-introduction-group Description ----------- -Plane represents a normalized plane equation. Basically, "normal" is the normal of the plane (a,b,c normalized), and "d" is the distance from the origin to the plane (in the direction of "normal"). "Over" or "Above" the plane is considered the side of the plane towards where the normal is pointing. +Represents a normalized plane equation. :ref:`normal` is the normal of the plane (a, b, c normalized), and :ref:`d` is the distance from the origin to the plane (in the direction of "normal"). "Over" or "Above" the plane is considered the side of the plane towards where the normal is pointing. .. rst-class:: classref-introduction-group diff --git a/classes/class_popup.rst b/classes/class_popup.rst index f8c9f3f7b8a..a02a1f19740 100644 --- a/classes/class_popup.rst +++ b/classes/class_popup.rst @@ -14,14 +14,14 @@ Popup **Inherited By:** :ref:`PopupMenu`, :ref:`PopupPanel` -Popup is a base window container for popup-like subwindows. +Base class for contextual windows and panels with fixed position. .. rst-class:: classref-introduction-group Description ----------- -Popup is a base window container for popup-like subwindows. It's a modal by default (see :ref:`Window.popup_window`) and has helpers for custom popup behavior. +**Popup** is a base class for contextual windows and panels with fixed position. It's a modal by default (see :ref:`Window.popup_window`) and provides methods for implementing custom popup behavior. .. rst-class:: classref-reftable-group diff --git a/classes/class_popupmenu.rst b/classes/class_popupmenu.rst index c6e0d44242a..2c7f2674a0c 100644 --- a/classes/class_popupmenu.rst +++ b/classes/class_popupmenu.rst @@ -12,20 +12,18 @@ PopupMenu **Inherits:** :ref:`Popup` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -PopupMenu displays a list of options. +A modal window used to display a list of options. .. rst-class:: classref-introduction-group Description ----------- -**PopupMenu** is a modal window used to display a list of options. They are popular in toolbars or context menus. +**PopupMenu** is a modal window used to display a list of options. Useful for toolbars and context menus. -The size of a **PopupMenu** can be limited by using :ref:`Window.max_size`. If the height of the list of items is larger than the maximum height of the **PopupMenu**, a :ref:`ScrollContainer` within the popup will allow the user to scroll the contents. +The size of a **PopupMenu** can be limited by using :ref:`Window.max_size`. If the height of the list of items is larger than the maximum height of the **PopupMenu**, a :ref:`ScrollContainer` within the popup will allow the user to scroll the contents. If no maximum size is set, or if it is set to ``0``, the **PopupMenu** height will be limited by its parent rect. -If no maximum size is set, or if it is set to 0, the **PopupMenu** height will be limited by its parent rect. - -All ``set_*`` methods allow negative item index, which makes the item accessed from the last one. +All ``set_*`` methods allow negative item indices, i.e. ``-1`` to access the last item, ``-2`` to select the second-to-last item, and so on. \ **Incremental search:** Like :ref:`ItemList` and :ref:`Tree`, **PopupMenu** supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing :ref:`ProjectSettings.gui/timers/incremental_search_max_interval_msec`. diff --git a/classes/class_popuppanel.rst b/classes/class_popuppanel.rst index 5f43de45d0e..f642f954380 100644 --- a/classes/class_popuppanel.rst +++ b/classes/class_popuppanel.rst @@ -12,16 +12,14 @@ PopupPanel **Inherits:** :ref:`Popup` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -Class for displaying popups with a panel background. +A popup with a panel background. .. rst-class:: classref-introduction-group Description ----------- -Class for displaying popups with a panel background. In some cases it might be simpler to use than :ref:`Popup`, since it provides a configurable background. If you are making windows, better check :ref:`Window`. - -If any :ref:`Control` node is added as a child of this **PopupPanel**, it will be stretched to fit the panel's size (similar to how :ref:`PanelContainer` works). +A popup with a configurable panel background. Any child controls added to this node will be stretched to fit the panel's size (similar to how :ref:`PanelContainer` works). If you are making windows, see :ref:`Window`. .. rst-class:: classref-reftable-group diff --git a/classes/class_progressbar.rst b/classes/class_progressbar.rst index 5d151668824..21d7e9c190d 100644 --- a/classes/class_progressbar.rst +++ b/classes/class_progressbar.rst @@ -12,14 +12,14 @@ ProgressBar **Inherits:** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -General-purpose progress bar. +A control used for visual representation of a percentage. .. rst-class:: classref-introduction-group Description ----------- -General-purpose progress bar. Shows fill percentage from right to left. +A control used for visual representation of a percentage. Shows fill percentage from right to left. .. rst-class:: classref-reftable-group diff --git a/classes/class_projection.rst b/classes/class_projection.rst index 863cb03d480..40b30c4b18c 100644 --- a/classes/class_projection.rst +++ b/classes/class_projection.rst @@ -10,7 +10,7 @@ Projection ========== -3D projection (4x4 matrix). +A 4×4 matrix for 3D projective transformations. .. rst-class:: classref-introduction-group @@ -19,7 +19,7 @@ Description A 4x4 matrix used for 3D projective transformations. It can represent transformations such as translation, rotation, scaling, shearing, and perspective division. It consists of four :ref:`Vector4` columns. -For purely linear transformations (translation, rotation, and scale), it is recommended to use :ref:`Transform3D`, as it is more performant and has a lower memory footprint. +For purely linear transformations (translation, rotation, and scale), it is recommended to use :ref:`Transform3D`, as it is more performant and requires less memory. Used internally as :ref:`Camera3D`'s projection matrix. diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index da1edfb1c87..69ece349f93 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -12,14 +12,14 @@ ProjectSettings **Inherits:** :ref:`Object` -Contains global variables accessible from everywhere. +Stores globally-accessible variables. .. rst-class:: classref-introduction-group Description ----------- -Contains global variables accessible from everywhere. Use :ref:`get_setting`, :ref:`set_setting` or :ref:`has_setting` to access them. Variables stored in ``project.godot`` are also loaded into ProjectSettings, making this object very useful for reading custom game configuration options. +Stores variables that can be accessed from everywhere. Use :ref:`get_setting`, :ref:`set_setting` or :ref:`has_setting` to access them. Variables stored in ``project.godot`` are also loaded into **ProjectSettings**, making this object very useful for reading custom game configuration options. When naming a Project Settings property, use the full path to the setting including the category. For example, ``"application/config/name"`` for the project name. Category and property names can be viewed in the Project Settings dialog. @@ -1415,6 +1415,8 @@ Properties +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`rendering/rendering_device/driver.windows` | ``"vulkan"`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rendering/rendering_device/pipeline_cache/save_chunk_size_mb` | ``3.0`` | + +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/rendering_device/staging_buffer/block_size_kb` | ``256`` | +---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rendering/rendering_device/staging_buffer/max_size_mb` | ``128`` | @@ -1535,6 +1537,8 @@ Methods +---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_as_basic` **(** :ref:`String` name, :ref:`bool` basic **)** | +---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`set_as_internal` **(** :ref:`String` name, :ref:`bool` internal **)** | + +---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_initial_value` **(** :ref:`String` name, :ref:`Variant` value **)** | +---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_order` **(** :ref:`String` name, :ref:`int` position **)** | @@ -3551,7 +3555,7 @@ Main window content is expanded to the full size of the window. Unlike a borderl :ref:`Vector2i` **display/window/size/initial_position** = ``Vector2i(0, 0)`` -Main window initial position (in virtual desktop coordinates), this settings is used only if :ref:`display/window/size/initial_position_type` is set to "Absolute" (``0``). +Main window initial position (in virtual desktop coordinates), this setting is used only if :ref:`display/window/size/initial_position_type` is set to "Absolute" (``0``). .. rst-class:: classref-item-separator @@ -3581,7 +3585,7 @@ Main window initial position. :ref:`int` **display/window/size/initial_screen** = ``0`` -Main window initial screen, this settings is used only if :ref:`display/window/size/initial_position_type` is set to "Other Screen Center" (``2``). +Main window initial screen, this setting is used only if :ref:`display/window/size/initial_position_type` is set to "Other Screen Center" (``2``). .. rst-class:: classref-item-separator @@ -3713,9 +3717,13 @@ On desktop platforms, overrides the game's initial window width. See also :ref:` :ref:`String` **display/window/stretch/mode** = ``"disabled"`` -.. container:: contribute +Defines how the base size is stretched to fit the resolution of the window or screen. - There is currently no description for this property. Please help us by :ref:`contributing one `! +\ **"disabled"**: No stretching happens. One unit in the scene corresponds to one pixel on the screen. In this mode, :ref:`display/window/stretch/aspect` has no effect. Recommended for non-game applications. + +\ **"canvas_items"**: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking :ref:`display/window/stretch/aspect` into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art aesthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). + +\ **"viewport"**: The size of the root :ref:`Viewport` is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking :ref:`display/window/stretch/aspect` into account). Recommended for games that use a pixel art aesthetic. .. rst-class:: classref-item-separator @@ -10257,6 +10265,18 @@ Windows override for :ref:`rendering/rendering_device/driver` **rendering/rendering_device/pipeline_cache/save_chunk_size_mb** = ``3.0`` + +Determines at which interval pipeline cache is saved to disk. The lower the value, the more often it is saved. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_property_rendering/rendering_device/staging_buffer/block_size_kb: .. rst-class:: classref-property @@ -10587,7 +10607,7 @@ If ``true``, the texture importer will import lossless textures using the PNG fo :ref:`bool` **rendering/textures/vram_compression/import_etc2_astc** -If ``true``, the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normalmaps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4x4 block size). +If ``true``, the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normal maps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4x4 block size). \ **Note:** Changing this setting does *not* impact textures that were already imported before. To make this setting apply to textures that were already imported, exit the editor, remove the ``.godot/imported/`` folder located inside the project folder then restart the editor (see :ref:`application/config/use_hidden_project_data_directory`). @@ -11093,6 +11113,18 @@ Defines if the specified setting is considered basic or advanced. Basic settings ---- +.. _class_ProjectSettings_method_set_as_internal: + +.. rst-class:: classref-method + +void **set_as_internal** **(** :ref:`String` name, :ref:`bool` internal **)** + +Defines if the specified setting is considered internal. An internal setting won't show up in the Project Settings dialog. This is mostly useful for addons that need to store their own internal settings without exposing them directly to the user. + +.. rst-class:: classref-item-separator + +---- + .. _class_ProjectSettings_method_set_initial_value: .. rst-class:: classref-method diff --git a/classes/class_randomnumbergenerator.rst b/classes/class_randomnumbergenerator.rst index da4decd0ae7..9035c6d1822 100644 --- a/classes/class_randomnumbergenerator.rst +++ b/classes/class_randomnumbergenerator.rst @@ -12,7 +12,7 @@ RandomNumberGenerator **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A class for generating pseudo-random numbers. +Provides methods for generating pseudo-random numbers. .. rst-class:: classref-introduction-group @@ -21,7 +21,7 @@ Description RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses `PCG32 `__. -\ **Note:** The underlying algorithm is an implementation detail. As a result, it should not be depended upon for reproducible random streams across Godot versions. +\ **Note:** The underlying algorithm is an implementation detail and should not be depended upon. To generate a random float number (within a given range) based on a time-dependant seed: @@ -31,8 +31,6 @@ To generate a random float number (within a given range) based on a time-dependa func _ready(): var my_random_number = rng.randf_range(-10.0, 10.0) -\ **Note:** The default values of :ref:`seed` and :ref:`state` properties are pseudo-random, and change when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. - .. rst-class:: classref-introduction-group Tutorials @@ -102,6 +100,8 @@ Initializes the random number generator state based on the given seed value. A g \ **Note:** Setting this property produces a side effect of changing the internal :ref:`state`, so make sure to initialize the seed *before* modifying the :ref:`state`: +\ **Note:** The default value of this property is pseudo-random, and changes when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. + :: var rng = RandomNumberGenerator.new() @@ -136,6 +136,8 @@ The current state of the random number generator. Save and restore this property \ **Note:** Do not set state to arbitrary values, since the random number generator requires the state to have certain qualities to behave properly. It should only be set to values that came from the state property itself. To initialize the random number generator with arbitrary input, use :ref:`seed` instead. +\ **Note:** The default value of this property is pseudo-random, and changes when calling :ref:`randomize`. The ``0`` value documented here is a placeholder, and not the actual default seed. + .. rst-class:: classref-section-separator ---- diff --git a/classes/class_range.rst b/classes/class_range.rst index 268e3c04fbb..b5e929edcda 100644 --- a/classes/class_range.rst +++ b/classes/class_range.rst @@ -14,14 +14,14 @@ Range **Inherited By:** :ref:`EditorSpinSlider`, :ref:`ProgressBar`, :ref:`ScrollBar`, :ref:`Slider`, :ref:`SpinBox`, :ref:`TextureProgressBar` -Abstract base class for range-based controls. +Abstract base class for controls that represent a number within a range. .. rst-class:: classref-introduction-group Description ----------- -Range is a base class for :ref:`Control` nodes that change a floating-point :ref:`value` between a :ref:`min_value` and :ref:`max_value`, using a configured :ref:`step` and :ref:`page` size. See e.g. :ref:`ScrollBar` and :ref:`Slider` for examples of higher level nodes using Range. +Range is an abstract base class for controls that represent a number within a range, using a configured :ref:`step` and :ref:`page` size. See e.g. :ref:`ScrollBar` and :ref:`Slider` for examples of higher-level nodes using Range. .. rst-class:: classref-reftable-group @@ -158,7 +158,7 @@ If ``true``, :ref:`value` may be less than :ref:`min - void **set_exp_ratio** **(** :ref:`bool` value **)** - :ref:`bool` **is_ratio_exp** **(** **)** -If ``true``, and ``min_value`` is greater than 0, ``value`` will be represented exponentially rather than linearly. +If ``true``, and :ref:`min_value` is greater than 0, :ref:`value` will be represented exponentially rather than linearly. .. rst-class:: classref-item-separator @@ -175,7 +175,7 @@ If ``true``, and ``min_value`` is greater than 0, ``value`` will be represented - void **set_max** **(** :ref:`float` value **)** - :ref:`float` **get_max** **(** **)** -Maximum value. Range is clamped if ``value`` is greater than ``max_value``. +Maximum value. Range is clamped if :ref:`value` is greater than :ref:`max_value`. .. rst-class:: classref-item-separator @@ -192,7 +192,7 @@ Maximum value. Range is clamped if ``value`` is greater than ``max_value``. - void **set_min** **(** :ref:`float` value **)** - :ref:`float` **get_min** **(** **)** -Minimum value. Range is clamped if ``value`` is less than ``min_value``. +Minimum value. Range is clamped if :ref:`value` is less than :ref:`min_value`. .. rst-class:: classref-item-separator @@ -209,7 +209,7 @@ Minimum value. Range is clamped if ``value`` is less than ``min_value``. - void **set_page** **(** :ref:`float` value **)** - :ref:`float` **get_page** **(** **)** -Page size. Used mainly for :ref:`ScrollBar`. ScrollBar's length is its size multiplied by ``page`` over the difference between ``min_value`` and ``max_value``. +Page size. Used mainly for :ref:`ScrollBar`. ScrollBar's length is its size multiplied by :ref:`page` over the difference between :ref:`min_value` and :ref:`max_value`. .. rst-class:: classref-item-separator @@ -243,7 +243,7 @@ The value mapped between 0 and 1. - void **set_use_rounded_values** **(** :ref:`bool` value **)** - :ref:`bool` **is_using_rounded_values** **(** **)** -If ``true``, ``value`` will always be rounded to the nearest integer. +If ``true``, :ref:`value` will always be rounded to the nearest integer. .. rst-class:: classref-item-separator @@ -260,7 +260,7 @@ If ``true``, ``value`` will always be rounded to the nearest integer. - void **set_step** **(** :ref:`float` value **)** - :ref:`float` **get_step** **(** **)** -If greater than 0, ``value`` will always be rounded to a multiple of ``step``. If ``rounded`` is also ``true``, ``value`` will first be rounded to a multiple of ``step`` then rounded to the nearest integer. +If greater than 0, :ref:`value` will always be rounded to a multiple of this property's value. If :ref:`rounded` is also ``true``, :ref:`value` will first be rounded to a multiple of this property's value, then rounded to the nearest integer. .. rst-class:: classref-item-separator diff --git a/classes/class_raycast2d.rst b/classes/class_raycast2d.rst index 67b34838c23..44803310bfd 100644 --- a/classes/class_raycast2d.rst +++ b/classes/class_raycast2d.rst @@ -12,22 +12,20 @@ RayCast2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Query the closest object intersecting a ray. +A ray in 2D space, used to find the first :ref:`CollisionObject2D` it intersects. .. rst-class:: classref-introduction-group Description ----------- -A RayCast represents a line from its origin to its destination position, :ref:`target_position`. It is used to query the 2D space in order to find the closest object along the path of the ray. +A raycast represents a ray from its origin to its :ref:`target_position` that finds the closest :ref:`CollisionObject2D` along its path, if it intersects any. This is useful for a lot of things, such as -RayCast2D can ignore some objects by adding them to the exception list via :ref:`add_exception`, by setting proper filtering with collision layers, or by filtering object types with type masks. +\ **RayCast2D** can ignore some objects by adding them to an exception list, by making its detection reporting ignore :ref:`Area2D`\ s (:ref:`collide_with_areas`) or :ref:`PhysicsBody2D`\ s (:ref:`collide_with_bodies`), or by configuring physics layers. -RayCast2D can be configured to report collisions with :ref:`Area2D`\ s (:ref:`collide_with_areas`) and/or :ref:`PhysicsBody2D`\ s (:ref:`collide_with_bodies`). +\ **RayCast2D** calculates intersection every physics frame, and it holds the result until the next physics frame. For an immediate raycast, or if you want to configure a **RayCast2D** multiple times within the same physics frame, use :ref:`force_raycast_update`. -Only enabled raycasts will be able to query the space and report collisions. - -RayCast2D calculates intersection every physics frame (see :ref:`Node`), and the result is cached so it can be used later until the next frame. If multiple queries are required between physics frames (or during the same frame) use :ref:`force_raycast_update` after adjusting the raycast. +To sweep over a region of 2D space, you can approximate the region with multiple **RayCast2D**\ s or use :ref:`ShapeCast2D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_raycast3d.rst b/classes/class_raycast3d.rst index 8b0ce193dd7..e297c936356 100644 --- a/classes/class_raycast3d.rst +++ b/classes/class_raycast3d.rst @@ -12,22 +12,20 @@ RayCast3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Query the closest object intersecting a ray. +A ray in 3D space, used to find the first :ref:`CollisionObject3D` it intersects. .. rst-class:: classref-introduction-group Description ----------- -A RayCast represents a line from its origin to its destination position, :ref:`target_position`. It is used to query the 3D space in order to find the closest object along the path of the ray. +A raycast represents a ray from its origin to its :ref:`target_position` that finds the closest :ref:`CollisionObject3D` along its path, if it intersects any. This is useful for a lot of things, such as -RayCast3D can ignore some objects by adding them to the exception list via :ref:`add_exception` or by setting proper filtering with collision layers and masks. +\ **RayCast3D** can ignore some objects by adding them to an exception list, by making its detection reporting ignore :ref:`Area3D`\ s (:ref:`collide_with_areas`) or :ref:`PhysicsBody3D`\ s (:ref:`collide_with_bodies`), or by configuring physics layers. -RayCast3D can be configured to report collisions with :ref:`Area3D`\ s (:ref:`collide_with_areas`) and/or :ref:`PhysicsBody3D`\ s (:ref:`collide_with_bodies`). +\ **RayCast3D** calculates intersection every physics frame, and it holds the result until the next physics frame. For an immediate raycast, or if you want to configure a **RayCast3D** multiple times within the same physics frame, use :ref:`force_raycast_update`. -Only enabled raycasts will be able to query the space and report collisions. - -RayCast3D calculates intersection every physics frame (see :ref:`Node`), and the result is cached so it can be used later until the next frame. If multiple queries are required between physics frames (or during the same frame), use :ref:`force_raycast_update` after adjusting the raycast. +To sweep over a region of 3D space, you can approximate the region with multiple **RayCast3D**\ s or use :ref:`ShapeCast3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_rect2.rst b/classes/class_rect2.rst index 0cdd2825f15..56cac772d4f 100644 --- a/classes/class_rect2.rst +++ b/classes/class_rect2.rst @@ -10,7 +10,7 @@ Rect2 ===== -2D axis-aligned bounding box using floating point coordinates. +A 2D axis-aligned bounding box using floating-point coordinates. .. rst-class:: classref-introduction-group diff --git a/classes/class_rect2i.rst b/classes/class_rect2i.rst index dd95f4806e0..93f84148bc7 100644 --- a/classes/class_rect2i.rst +++ b/classes/class_rect2i.rst @@ -10,7 +10,7 @@ Rect2i ====== -2D axis-aligned bounding box using integer coordinates. +A 2D axis-aligned bounding box using integer coordinates. .. rst-class:: classref-introduction-group diff --git a/classes/class_rectangleshape2d.rst b/classes/class_rectangleshape2d.rst index ef5a7c90ccc..e6b3d16daf3 100644 --- a/classes/class_rectangleshape2d.rst +++ b/classes/class_rectangleshape2d.rst @@ -12,16 +12,16 @@ RectangleShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Rectangle shape resource for 2D physics. +A 2D rectangle shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D rectangle shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. This shape is useful for modeling box-like 2D objects. +A 2D rectangle shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. -\ **Performance:** Being a primitive collision shape, **RectangleShape2D** is fast to check collisions against (though not as fast as :ref:`CircleShape2D`). +\ **Performance:** **RectangleShape2D** is fast to check collisions against. It is faster than :ref:`CapsuleShape2D`, but slower than :ref:`CircleShape2D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_referencerect.rst b/classes/class_referencerect.rst index 07ba31e158d..46ec484f645 100644 --- a/classes/class_referencerect.rst +++ b/classes/class_referencerect.rst @@ -12,14 +12,14 @@ ReferenceRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Reference frame for GUI. +A rectangle hint for designing UIs. .. rst-class:: classref-introduction-group Description ----------- -A rectangle box that displays only a :ref:`border_color` border color around its rectangle. **ReferenceRect** has no fill :ref:`Color`. If you need to display a rectangle filled with a solid color, consider using :ref:`ColorRect` instead. +A rectangle box that displays only a colored border around its rectangle. It is used to visualize the extents of a :ref:`Control`. .. rst-class:: classref-reftable-group @@ -57,7 +57,7 @@ Property Descriptions - void **set_border_color** **(** :ref:`Color` value **)** - :ref:`Color` **get_border_color** **(** **)** -Sets the border :ref:`Color` of the **ReferenceRect**. +Sets the border color of the **ReferenceRect**. .. rst-class:: classref-item-separator diff --git a/classes/class_renderingdevice.rst b/classes/class_renderingdevice.rst index 3de4deade10..e129ca8b76d 100644 --- a/classes/class_renderingdevice.rst +++ b/classes/class_renderingdevice.rst @@ -4391,7 +4391,7 @@ void **compute_list_add_barrier** **(** :ref:`int` compute_list **)** Starts a list of compute commands created with the ``compute_*`` methods. The returned value should be passed to other ``compute_list_*`` functions. -If ``allow_draw_overlap`` is true, you may have one draw list running at the same time as one compute list. Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using :ref:`compute_list_end`. +If ``allow_draw_overlap`` is ``true``, you may have one draw list running at the same time as one compute list. Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using :ref:`compute_list_end`. A simple compute operation might look like this (code is not a complete example): diff --git a/classes/class_renderingserver.rst b/classes/class_renderingserver.rst index 7706ea4b734..ffeb745efb3 100644 --- a/classes/class_renderingserver.rst +++ b/classes/class_renderingserver.rst @@ -1216,7 +1216,7 @@ Array is a vertex color array. :ref:`ArrayType` **ARRAY_TEX_UV** = ``4`` -Array is an UV coordinates array. +Array is a UV coordinates array. .. _class_RenderingServer_constant_ARRAY_TEX_UV2: @@ -1224,7 +1224,7 @@ Array is an UV coordinates array. :ref:`ArrayType` **ARRAY_TEX_UV2** = ``5`` -Array is an UV coordinates array for the second set of UV coordinates. +Array is a UV coordinates array for the second set of UV coordinates. .. _class_RenderingServer_constant_ARRAY_CUSTOM0: @@ -1420,7 +1420,7 @@ Flag used to mark a vertex color array. :ref:`ArrayFormat` **ARRAY_FORMAT_TEX_UV** = ``16`` -Flag used to mark an UV coordinates array. +Flag used to mark a UV coordinates array. .. _class_RenderingServer_constant_ARRAY_FORMAT_TEX_UV2: @@ -1428,7 +1428,7 @@ Flag used to mark an UV coordinates array. :ref:`ArrayFormat` **ARRAY_FORMAT_TEX_UV2** = ``32`` -Flag used to mark an UV coordinates array for the second UV coordinates. +Flag used to mark a UV coordinates array for the second UV coordinates. .. _class_RenderingServer_constant_ARRAY_FORMAT_CUSTOM0: diff --git a/classes/class_resource.rst b/classes/class_resource.rst index 90e8c5ac906..f1f9c02b1dc 100644 --- a/classes/class_resource.rst +++ b/classes/class_resource.rst @@ -14,7 +14,7 @@ Resource **Inherited By:** :ref:`Animation`, :ref:`AnimationLibrary`, :ref:`AnimationNode`, :ref:`AnimationNodeStateMachinePlayback`, :ref:`AnimationNodeStateMachineTransition`, :ref:`AudioBusLayout`, :ref:`AudioEffect`, :ref:`AudioStream`, :ref:`BitMap`, :ref:`BoneMap`, :ref:`ButtonGroup`, :ref:`CameraAttributes`, :ref:`CryptoKey`, :ref:`Curve`, :ref:`Curve2D`, :ref:`Curve3D`, :ref:`EditorNode3DGizmoPlugin`, :ref:`EditorSettings`, :ref:`Environment`, :ref:`Font`, :ref:`GDExtension`, :ref:`GLTFAccessor`, :ref:`GLTFAnimation`, :ref:`GLTFBufferView`, :ref:`GLTFCamera`, :ref:`GLTFCollider`, :ref:`GLTFDocument`, :ref:`GLTFDocumentExtension`, :ref:`GLTFLight`, :ref:`GLTFMesh`, :ref:`GLTFNode`, :ref:`GLTFPhysicsBody`, :ref:`GLTFSkeleton`, :ref:`GLTFSkin`, :ref:`GLTFSpecGloss`, :ref:`GLTFState`, :ref:`GLTFTexture`, :ref:`GLTFTextureSampler`, :ref:`Gradient`, :ref:`Image`, :ref:`ImporterMesh`, :ref:`InputEvent`, :ref:`JSON`, :ref:`LabelSettings`, :ref:`LightmapGIData`, :ref:`Material`, :ref:`Mesh`, :ref:`MeshLibrary`, :ref:`MissingResource`, :ref:`MultiMesh`, :ref:`NavigationMesh`, :ref:`NavigationPolygon`, :ref:`Noise`, :ref:`Occluder3D`, :ref:`OccluderPolygon2D`, :ref:`OggPacketSequence`, :ref:`OpenXRAction`, :ref:`OpenXRActionMap`, :ref:`OpenXRActionSet`, :ref:`OpenXRInteractionProfile`, :ref:`OpenXRIPBinding`, :ref:`PackedDataContainer`, :ref:`PackedScene`, :ref:`PhysicsMaterial`, :ref:`PolygonPathFinder`, :ref:`RDShaderFile`, :ref:`RDShaderSPIRV`, :ref:`RichTextEffect`, :ref:`SceneReplicationConfig`, :ref:`Script`, :ref:`Shader`, :ref:`ShaderInclude`, :ref:`Shape2D`, :ref:`Shape3D`, :ref:`Shortcut`, :ref:`SkeletonModification2D`, :ref:`SkeletonModificationStack2D`, :ref:`SkeletonProfile`, :ref:`Skin`, :ref:`Sky`, :ref:`SpriteFrames`, :ref:`StyleBox`, :ref:`SyntaxHighlighter`, :ref:`Texture`, :ref:`Theme`, :ref:`TileMapPattern`, :ref:`TileSet`, :ref:`TileSetSource`, :ref:`Translation`, :ref:`VideoStream`, :ref:`VideoStreamPlayback`, :ref:`VisualShaderNode`, :ref:`VoxelGIData`, :ref:`World2D`, :ref:`World3D`, :ref:`X509Certificate` -Base class for all resources. +Base class for serializable objects. .. rst-class:: classref-introduction-group @@ -163,7 +163,7 @@ An optional name for this resource. When defined, its value is displayed to repr - void **set_path** **(** :ref:`String` value **)** - :ref:`String` **get_path** **(** **)** -The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the :ref:`PackedScene`'s filepath, followed by an unique identifier. +The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the :ref:`PackedScene`'s filepath, followed by a unique identifier. \ **Note:** Setting this property manually may fail if a resource with the same path has already been previously loaded. If necessary, use :ref:`take_over_path`. diff --git a/classes/class_resourceimporter.rst b/classes/class_resourceimporter.rst index 7345044b4d1..ff97a6b7b59 100644 --- a/classes/class_resourceimporter.rst +++ b/classes/class_resourceimporter.rst @@ -14,14 +14,14 @@ ResourceImporter **Inherited By:** :ref:`EditorImportPlugin` -Base class for the implementation of core resource importers. +Base class for resource importers. .. rst-class:: classref-introduction-group Description ----------- -This is the base class for the resource importers implemented in core. To implement your own resource importers using editor plugins, see :ref:`EditorImportPlugin`. +This is the base class for Godot's resource importers. To implement your own resource importers using editor plugins, see :ref:`EditorImportPlugin`. .. rst-class:: classref-introduction-group diff --git a/classes/class_resourceloader.rst b/classes/class_resourceloader.rst index bd0674322b2..98461fa14d3 100644 --- a/classes/class_resourceloader.rst +++ b/classes/class_resourceloader.rst @@ -12,14 +12,14 @@ ResourceLoader **Inherits:** :ref:`Object` -Singleton used to load resource files. +A singleton for loading resource files. .. rst-class:: classref-introduction-group Description ----------- -Singleton used to load resource files from the filesystem. +A singleton used to load resource files from the filesystem. It uses the many :ref:`ResourceFormatLoader` classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine. diff --git a/classes/class_resourcepreloader.rst b/classes/class_resourcepreloader.rst index 6bb60162c60..6f410f39d3a 100644 --- a/classes/class_resourcepreloader.rst +++ b/classes/class_resourcepreloader.rst @@ -12,7 +12,7 @@ ResourcePreloader **Inherits:** :ref:`Node` **<** :ref:`Object` -Preloads a list of resources inside a scene. +A node used to preload sub-resources inside a scene. .. rst-class:: classref-introduction-group diff --git a/classes/class_resourcesaver.rst b/classes/class_resourcesaver.rst index 3b8b19627db..50656783a9d 100644 --- a/classes/class_resourcesaver.rst +++ b/classes/class_resourcesaver.rst @@ -12,16 +12,16 @@ ResourceSaver **Inherits:** :ref:`Object` -Singleton for saving Godot-specific resource types. +A singleton for saving :ref:`Resource`\ s to the filesystem. .. rst-class:: classref-introduction-group Description ----------- -Singleton for saving Godot-specific resource types to the filesystem. +A singleton for saving resource types to the filesystem. -It uses the many :ref:`ResourceFormatSaver` classes registered in the engine (either built-in or from a plugin) to save engine-specific resource data to text-based (e.g. ``.tres`` or ``.tscn``) or binary files (e.g. ``.res`` or ``.scn``). +It uses the many :ref:`ResourceFormatSaver` classes registered in the engine (either built-in or from a plugin) to save resource data to text-based (e.g. ``.tres`` or ``.tscn``) or binary files (e.g. ``.res`` or ``.scn``). .. rst-class:: classref-reftable-group diff --git a/classes/class_resourceuid.rst b/classes/class_resourceuid.rst index 7eb32998ab7..017cb0889a1 100644 --- a/classes/class_resourceuid.rst +++ b/classes/class_resourceuid.rst @@ -12,18 +12,16 @@ ResourceUID **Inherits:** :ref:`Object` -Singleton for managing a cache of resource UIDs within a project. +A singleton that manages the unique identifiers of all resources within a project. .. rst-class:: classref-introduction-group Description ----------- -Resources can not only be referenced using their resource paths ``res://``, but alternatively through a unique identifier specified via ``uid://``. +Resource UIDs (Unique IDentifiers) allow the engine to keep references between resources intact, even if files can renamed or moved. They can be accessed with ``uid://``. -Using UIDs allows for the engine to keep references between resources intact, even if the files get renamed or moved. - -This singleton is responsible for keeping track of all registered resource UIDs of a project, generating new UIDs and converting between the string and integer representation. +\ **ResourceUID** keeps track of all registered resource UIDs in a project, generates new UIDs, and converts between their string and integer representations. .. rst-class:: classref-reftable-group diff --git a/classes/class_richtexteffect.rst b/classes/class_richtexteffect.rst index 0f492faec7c..6a24aa8e717 100644 --- a/classes/class_richtexteffect.rst +++ b/classes/class_richtexteffect.rst @@ -12,14 +12,14 @@ RichTextEffect **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -A custom effect for use with :ref:`RichTextLabel`. +A custom effect for a :ref:`RichTextLabel`. .. rst-class:: classref-introduction-group Description ----------- -A custom effect for use with :ref:`RichTextLabel`. +A custom effect for a :ref:`RichTextLabel`. \ **Note:** For a **RichTextEffect** to be usable, a BBCode tag must be defined as a member variable called ``bbcode`` in the script. diff --git a/classes/class_richtextlabel.rst b/classes/class_richtextlabel.rst index 52cf82de64f..3f45c60168c 100644 --- a/classes/class_richtextlabel.rst +++ b/classes/class_richtextlabel.rst @@ -12,22 +12,22 @@ RichTextLabel **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Label that displays rich text. +A control for displaying text that can contain different font styles, images, and basic formatting. .. rst-class:: classref-introduction-group Description ----------- -Rich text can contain custom text, fonts, images and some basic formatting. The label manages these as an internal tag stack. It also adapts itself to given width/heights. +A control for displaying text that can contain custom fonts, images, and basic formatting. **RichTextLabel** manages these as an internal tag stack. It also adapts itself to given width/heights. \ **Note:** Assignments to :ref:`text` clear the tag stack and reconstruct it from the property's contents. Any edits made to :ref:`text` will erase previous edits made from other manual sources such as :ref:`append_text` and the ``push_*`` / :ref:`pop` methods. \ **Note:** RichTextLabel doesn't support entangled BBCode tags. For example, instead of using ``[b]bold[i]bold italic[/b]italic[/i]``, use ``[b]bold[i]bold italic[/i][/b][i]italic[/i]``. -\ **Note:** ``push_*/pop`` functions won't affect BBCode. +\ **Note:** ``push_*/pop_*`` functions won't affect BBCode. -\ **Note:** Unlike :ref:`Label`, RichTextLabel doesn't have a *property* to horizontally align text to the center. Instead, enable :ref:`bbcode_enabled` and surround the text in a ``[center]`` tag as follows: ``[center]Example[/center]``. There is currently no built-in way to vertically align text either, but this can be emulated by relying on anchors/containers and the :ref:`fit_content` property. +\ **Note:** Unlike :ref:`Label`, **RichTextLabel** doesn't have a *property* to horizontally align text to the center. Instead, enable :ref:`bbcode_enabled` and surround the text in a ``[center]`` tag as follows: ``[center]Example[/center]``. There is currently no built-in way to vertically align text either, but this can be emulated by relying on anchors/containers and the :ref:`fit_content` property. .. rst-class:: classref-introduction-group diff --git a/classes/class_rid.rst b/classes/class_rid.rst index 337316d481f..607c40960e7 100644 --- a/classes/class_rid.rst +++ b/classes/class_rid.rst @@ -10,7 +10,7 @@ RID === -Handle for a :ref:`Resource`'s unique ID. +A handle for a :ref:`Resource`'s unique identifier. .. rst-class:: classref-introduction-group diff --git a/classes/class_rigidbody2d.rst b/classes/class_rigidbody2d.rst index 374abe301dd..c4461121784 100644 --- a/classes/class_rigidbody2d.rst +++ b/classes/class_rigidbody2d.rst @@ -14,22 +14,22 @@ RigidBody2D **Inherited By:** :ref:`PhysicalBone2D` -Physics Body which is moved by 2D physics simulation. Useful for objects that have gravity and can be pushed by other objects. +A 2D physics body that is moved by a physics simulation. .. rst-class:: classref-introduction-group Description ----------- -This node implements simulated 2D physics. You do not control a RigidBody2D directly. Instead, you apply forces to it (gravity, impulses, etc.) and the physics simulation calculates the resulting movement based on its mass, friction, and other physical properties. +**RigidBody2D** implements full 2D physics. It cannot be controlled directly, instead, you must apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, rotation, react to collisions, and affect other physics bodies in its path. -You can switch the body's behavior using :ref:`lock_rotation`, :ref:`freeze`, and :ref:`freeze_mode`. +The body's behavior can be adjusted via :ref:`lock_rotation`, :ref:`freeze`, and :ref:`freeze_mode`. By changing various properties of the object, such as :ref:`mass`, you can control how the physics simulation acts on it. -\ **Note:** You should not change a RigidBody2D's ``position`` or ``linear_velocity`` every frame or even very often. If you need to directly affect the body's state, use :ref:`_integrate_forces`, which allows you to directly access the physics state. +A rigid body will always maintain its shape and size, even when forces are applied to it. It is useful for objects that can be interacted with in an environment, such as a tree that can be knocked over or a stack of crates that can be pushed around. -Please also keep in mind that physics bodies manage their own transform which overwrites the ones you set. So any direct or indirect transformation (including scaling of the node or its parent) will be visible in the editor only, and immediately reset at runtime. +If you need to override the default physics behavior, you can write a custom force integration function. See :ref:`custom_integrator`. -If you need to override the default physics behavior or add a transformation at runtime, you can write a custom force integration. See :ref:`custom_integrator`. +\ **Note:** Changing the 2D transform or :ref:`linear_velocity` of a **RigidBody2D** very often may lead to some unpredictable behaviors. If you need to directly affect the body, prefer :ref:`_integrate_forces` as it allows you to directly access the physics state. .. rst-class:: classref-introduction-group diff --git a/classes/class_rigidbody3d.rst b/classes/class_rigidbody3d.rst index 40b9a7cd5be..917578da3d7 100644 --- a/classes/class_rigidbody3d.rst +++ b/classes/class_rigidbody3d.rst @@ -14,22 +14,22 @@ RigidBody3D **Inherited By:** :ref:`VehicleBody3D` -Physics Body which is moved by 3D physics simulation. Useful for objects that have gravity and can be pushed by other objects. +A 3D physics body that is moved by a physics simulation. .. rst-class:: classref-introduction-group Description ----------- -This is the node that implements full 3D physics. This means that you do not control a RigidBody3D directly. Instead, you can apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, collision, bouncing, rotating, etc. +**RigidBody3D** implements full 3D physics. It cannot be controlled directly, instead, you must apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, rotation, react to collisions, and affect other physics bodies in its path. -You can switch the body's behavior using :ref:`lock_rotation`, :ref:`freeze`, and :ref:`freeze_mode`. +The body's behavior can be adjusted via :ref:`lock_rotation`, :ref:`freeze`, and :ref:`freeze_mode`. By changing various properties of the object, such as :ref:`mass`, you can control how the physics simulation acts on it. -\ **Note:** Don't change a RigidBody3D's position every frame or very often. Sporadic changes work fine, but physics runs at a different granularity (fixed Hz) than usual rendering (process callback) and maybe even in a separate thread, so changing this from a process loop may result in strange behavior. If you need to directly affect the body's state, use :ref:`_integrate_forces`, which allows you to directly access the physics state. +A rigid body will always maintain its shape and size, even when forces are applied to it. It is useful for objects that can be interacted with in an environment, such as a tree that can be knocked over or a stack of crates that can be pushed around. If you need to override the default physics behavior, you can write a custom force integration function. See :ref:`custom_integrator`. -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +\ **Note:** Changing the 3D transform or :ref:`linear_velocity` of a **RigidBody3D** very often may lead to some unpredictable behaviors. If you need to directly affect the body, prefer :ref:`_integrate_forces` as it allows you to directly access the physics state. .. rst-class:: classref-introduction-group diff --git a/classes/class_scenestate.rst b/classes/class_scenestate.rst index efbccb858dc..f93881442da 100644 --- a/classes/class_scenestate.rst +++ b/classes/class_scenestate.rst @@ -12,14 +12,14 @@ SceneState **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A script interface to a scene file's data. +Provides access to a scene file's information. .. rst-class:: classref-introduction-group Description ----------- -Maintains a list of resources, nodes, exported, and overridden properties, and built-in scripts associated with a scene. +Maintains a list of resources, nodes, exported and overridden properties, and built-in scripts associated with a scene. They cannot be modified from a **SceneState**, only accessed. Useful for peeking into what a :ref:`PackedScene` contains without instantiating it. This class cannot be instantiated directly, it is retrieved for a given scene as the result of :ref:`PackedScene.get_state`. diff --git a/classes/class_scriptcreatedialog.rst b/classes/class_scriptcreatedialog.rst index 309943f5713..84f396767ee 100644 --- a/classes/class_scriptcreatedialog.rst +++ b/classes/class_scriptcreatedialog.rst @@ -12,7 +12,7 @@ ScriptCreateDialog **Inherits:** :ref:`ConfirmationDialog` **<** :ref:`AcceptDialog` **<** :ref:`Window` **<** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -The Editor's popup dialog for creating new :ref:`Script` files. +Godot editor's popup dialog for creating new :ref:`Script` files. .. rst-class:: classref-introduction-group diff --git a/classes/class_scripteditor.rst b/classes/class_scripteditor.rst index c529f12818c..14a36a4e8be 100644 --- a/classes/class_scripteditor.rst +++ b/classes/class_scripteditor.rst @@ -19,7 +19,9 @@ Godot editor's script editor. Description ----------- -**Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_script_editor`. +Godot editor's script editor. + +\ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_script_editor`. .. rst-class:: classref-reftable-group diff --git a/classes/class_scripteditorbase.rst b/classes/class_scripteditorbase.rst index b8afb1d4a2d..a6d32bce577 100644 --- a/classes/class_scripteditorbase.rst +++ b/classes/class_scripteditorbase.rst @@ -19,7 +19,7 @@ Base editor for editing scripts in the :ref:`ScriptEditor`. Description ----------- -Base editor for editing scripts in the :ref:`ScriptEditor`, this does not include documentation items. +Base editor for editing scripts in the :ref:`ScriptEditor`. This does not include documentation items. .. rst-class:: classref-reftable-group diff --git a/classes/class_scrollbar.rst b/classes/class_scrollbar.rst index f457a8be0c2..67a23780953 100644 --- a/classes/class_scrollbar.rst +++ b/classes/class_scrollbar.rst @@ -14,14 +14,14 @@ ScrollBar **Inherited By:** :ref:`HScrollBar`, :ref:`VScrollBar` -Base class for scroll bars. +Abstract base class for scrollbars. .. rst-class:: classref-introduction-group Description ----------- -Scrollbars are a :ref:`Range`-based :ref:`Control`, that display a draggable area (the size of the page). Horizontal (:ref:`HScrollBar`) and Vertical (:ref:`VScrollBar`) versions are available. +Abstract base class for scrollbars, typically used to navigate through content that extends beyond the visible area of a control. Scrollbars are :ref:`Range`-based controls. .. rst-class:: classref-reftable-group diff --git a/classes/class_scrollcontainer.rst b/classes/class_scrollcontainer.rst index 896d1a5cb51..3d6eaf5656c 100644 --- a/classes/class_scrollcontainer.rst +++ b/classes/class_scrollcontainer.rst @@ -14,25 +14,21 @@ ScrollContainer **Inherited By:** :ref:`EditorInspector` -A helper node for displaying scrollable elements such as lists. +A container used to provide scrollbars to a child control when needed. .. rst-class:: classref-introduction-group Description ----------- -A ScrollContainer node meant to contain a :ref:`Control` child. - -ScrollContainers will automatically create a scrollbar child (:ref:`HScrollBar`, :ref:`VScrollBar`, or both) when needed and will only draw the Control within the ScrollContainer area. Scrollbars will automatically be drawn at the right (for vertical) or bottom (for horizontal) and will enable dragging to move the viewable Control (and its children) within the ScrollContainer. Scrollbars will also automatically resize the grabber based on the :ref:`Control.custom_minimum_size` of the Control relative to the ScrollContainer. - -Works great with a :ref:`Panel` control. You can set :ref:`Control.SIZE_EXPAND` on the children's size flags, so they will upscale to the ScrollContainer's size if it's larger (scroll is invisible for the chosen dimension). +A container used to provide a child control with scrollbars when needed. Scrollbars will automatically be drawn at the right (for vertical) or bottom (for horizontal) and will enable dragging to move the viewable Control (and its children) within the ScrollContainer. Scrollbars will also automatically resize the grabber based on the :ref:`Control.custom_minimum_size` of the Control relative to the ScrollContainer. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_segmentshape2d.rst b/classes/class_segmentshape2d.rst index 984b4fd75c1..2111fe1edb3 100644 --- a/classes/class_segmentshape2d.rst +++ b/classes/class_segmentshape2d.rst @@ -12,16 +12,14 @@ SegmentShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Segment shape resource for 2D physics. +A 2D line segment shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D segment shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. Consists of two points, ``a`` and ``b``. - -\ **Performance:** Being a primitive collision shape, **SegmentShape2D** is fast to check collisions against (though not as fast as :ref:`CircleShape2D`). +A 2D line segment shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. .. rst-class:: classref-reftable-group diff --git a/classes/class_semaphore.rst b/classes/class_semaphore.rst index aa951296f86..a91daee5d96 100644 --- a/classes/class_semaphore.rst +++ b/classes/class_semaphore.rst @@ -12,22 +12,22 @@ Semaphore **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -A synchronization semaphore. +A synchronization mechanism used to control access to a shared resource by :ref:`Thread`\ s. .. rst-class:: classref-introduction-group Description ----------- -A synchronization semaphore which can be used to synchronize multiple :ref:`Thread`\ s. Initialized to zero on creation. Be careful to avoid deadlocks. For a binary version, see :ref:`Mutex`. +A synchronization semaphore that can be used to synchronize multiple :ref:`Thread`\ s. Initialized to zero on creation. For a binary version, see :ref:`Mutex`. -\ **Warning:**\ +\ **Warning:** Semaphores must be used carefully to avoid deadlocks. -To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met: +\ **Warning:** To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met: -- By the time a **Semaphore**'s reference count reaches zero and therefore it is destroyed, no threads must be waiting on it. +- When a **Semaphore**'s reference count reaches zero and it is therefore destroyed, no threads must be waiting on it. -- By the time a :ref:`Thread`'s reference count reaches zero and therefore it is destroyed, it must not be waiting on any semaphore. +- When a :ref:`Thread`'s reference count reaches zero and it is therefore destroyed, it must not be waiting on any semaphore. .. rst-class:: classref-introduction-group @@ -36,6 +36,8 @@ Tutorials - :doc:`Using multiple threads <../tutorials/performance/using_multiple_threads>` +- :doc:`Thread-safe APIs <../tutorials/performance/thread_safe_apis>` + .. rst-class:: classref-reftable-group Methods diff --git a/classes/class_separationrayshape2d.rst b/classes/class_separationrayshape2d.rst index 1874487eef9..a066de816a1 100644 --- a/classes/class_separationrayshape2d.rst +++ b/classes/class_separationrayshape2d.rst @@ -12,16 +12,14 @@ SeparationRayShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Separation ray shape resource for 2D physics. +A 2D ray shape used for physics collision that tries to separate itself from any collider. .. rst-class:: classref-introduction-group Description ----------- -2D separation ray shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. A ray is not really a collision body; instead, it tries to separate itself from whatever is touching its far endpoint. It's often useful for characters. - -\ **Performance:** Being a primitive collision shape, **SeparationRayShape2D** is fast to check collisions against. +A 2D ray shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. When a **SeparationRayShape2D** collides with an object, it tries to separate itself from it by moving its endpoint to the collision point. It can for example be used for spears falling from the sky. .. rst-class:: classref-reftable-group diff --git a/classes/class_separationrayshape3d.rst b/classes/class_separationrayshape3d.rst index b31ecff06d5..5071c20dc8c 100644 --- a/classes/class_separationrayshape3d.rst +++ b/classes/class_separationrayshape3d.rst @@ -12,16 +12,14 @@ SeparationRayShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Separation ray shape resource for 3D physics. +A 3D ray shape used for physics collision that tries to separate itself from any collider. .. rst-class:: classref-introduction-group Description ----------- -3D separation ray shape to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. A ray is not really a collision body; instead, it tries to separate itself from whatever is touching its far endpoint. It's often useful for characters. - -\ **Performance:** Being a primitive collision shape, **SeparationRayShape3D** is fast to check collisions against. +A 3D ray shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape2D`. When a **SeparationRayShape3D** collides with an object, it tries to separate itself from it by moving its endpoint to the collision point. It can for example be used for spears falling from the sky. .. rst-class:: classref-reftable-group diff --git a/classes/class_separator.rst b/classes/class_separator.rst index 4031a84cd64..19265910c03 100644 --- a/classes/class_separator.rst +++ b/classes/class_separator.rst @@ -14,14 +14,14 @@ Separator **Inherited By:** :ref:`HSeparator`, :ref:`VSeparator` -Base class for separators. +Abstract base class for separators. .. rst-class:: classref-introduction-group Description ----------- -Separator is a :ref:`Control` used for separating other controls. It's purely a visual decoration. Horizontal (:ref:`HSeparator`) and Vertical (:ref:`VSeparator`) versions are available. +Abstract base class for separators, used for separating other controls. **Separator**\ s are purely visual and normally drawn as a :ref:`StyleBoxLine`. .. |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_shape2d.rst b/classes/class_shape2d.rst index 44d87f9bdc8..ab2b622ba8a 100644 --- a/classes/class_shape2d.rst +++ b/classes/class_shape2d.rst @@ -14,14 +14,16 @@ Shape2D **Inherited By:** :ref:`CapsuleShape2D`, :ref:`CircleShape2D`, :ref:`ConcavePolygonShape2D`, :ref:`ConvexPolygonShape2D`, :ref:`RectangleShape2D`, :ref:`SegmentShape2D`, :ref:`SeparationRayShape2D`, :ref:`WorldBoundaryShape2D` -Base class for all 2D shapes. +Abstract base class for 2D shapes used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -Base class for all 2D shapes. All 2D shape types inherit from this. +Abstract base class for all 2D shapes, intended for use in physics. + +\ **Performance:** Primitive shapes, especially :ref:`CircleShape2D`, are fast to check collisions against. :ref:`ConvexPolygonShape2D` is slower, and :ref:`ConcavePolygonShape2D` is the slowest. .. rst-class:: classref-introduction-group diff --git a/classes/class_shape3d.rst b/classes/class_shape3d.rst index 3caa0b82ed3..a952f717f1f 100644 --- a/classes/class_shape3d.rst +++ b/classes/class_shape3d.rst @@ -14,14 +14,16 @@ Shape3D **Inherited By:** :ref:`BoxShape3D`, :ref:`CapsuleShape3D`, :ref:`ConcavePolygonShape3D`, :ref:`ConvexPolygonShape3D`, :ref:`CylinderShape3D`, :ref:`HeightMapShape3D`, :ref:`SeparationRayShape3D`, :ref:`SphereShape3D`, :ref:`WorldBoundaryShape3D` -Base class for all 3D shape resources. +Abstract base class for 3D shapes used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -Base class for all 3D shape resources. Nodes that inherit from this can be used as shapes for a :ref:`PhysicsBody3D` or :ref:`Area3D` objects. +Abstract base class for all 3D shapes, intended for use in physics. + +\ **Performance:** Primitive shapes, especially :ref:`SphereShape3D`, are fast to check collisions against. :ref:`ConvexPolygonShape3D` and :ref:`HeightMapShape3D` are slower, and :ref:`ConcavePolygonShape3D` is the slowest. .. rst-class:: classref-introduction-group diff --git a/classes/class_shapecast2d.rst b/classes/class_shapecast2d.rst index fb89a2f2fba..1c7dcc7cb16 100644 --- a/classes/class_shapecast2d.rst +++ b/classes/class_shapecast2d.rst @@ -12,20 +12,18 @@ ShapeCast2D **Inherits:** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Node for physics collision sweep and immediate overlap queries. Similar to the :ref:`RayCast2D` node. +A 2D shape that sweeps a region of space to detect :ref:`CollisionObject2D`\ s. .. rst-class:: classref-introduction-group Description ----------- -Shape casting allows to detect collision objects by sweeping the :ref:`shape` along the cast direction determined by :ref:`target_position` (useful for things like beam weapons). +Shape casting allows to detect collision objects by sweeping its :ref:`shape` along the cast direction determined by :ref:`target_position`. This is similar to :ref:`RayCast2D`, but it allows for sweeping a region of space, rather than just a straight line. **ShapeCast2D** can detect multiple collision objects. It is useful for things like wide laser beams or snapping a simple shape to a floor. -Immediate collision overlaps can be done with the :ref:`target_position` set to ``Vector2(0, 0)`` and by calling :ref:`force_shapecast_update` within the same **physics frame**. This also helps to overcome some limitations of :ref:`Area2D` when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to :ref:`Area2D` nodes, and when using the signals creates unnecessary complexity. +Immediate collision overlaps can be done with the :ref:`target_position` set to ``Vector2(0, 0)`` and by calling :ref:`force_shapecast_update` within the same physics frame. This helps to overcome some limitations of :ref:`Area2D` when used as an instantaneous detection area, as collision information isn't immediately available to it. -The node can detect multiple collision objects, but it's usually used to detect the first collision. - -\ **Note:** shape casting is more computationally expensive compared to ray casting. +\ **Note:** Shape casting is more computationally expensive than ray casting. .. rst-class:: classref-reftable-group diff --git a/classes/class_shapecast3d.rst b/classes/class_shapecast3d.rst index f1627d9f108..147b53d86ac 100644 --- a/classes/class_shapecast3d.rst +++ b/classes/class_shapecast3d.rst @@ -12,20 +12,18 @@ ShapeCast3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Node for physics collision sweep and immediate overlap queries. Similar to the :ref:`RayCast3D` node. +A 3D shape that sweeps a region of space to detect :ref:`CollisionObject3D`\ s. .. rst-class:: classref-introduction-group Description ----------- -Shape casting allows to detect collision objects by sweeping the :ref:`shape` along the cast direction determined by :ref:`target_position` (useful for things like beam weapons). +Shape casting allows to detect collision objects by sweeping its :ref:`shape` along the cast direction determined by :ref:`target_position`. This is similar to :ref:`RayCast3D`, but it allows for sweeping a region of space, rather than just a straight line. **ShapeCast3D** can detect multiple collision objects. It is useful for things like wide laser beams or snapping a simple shape to a floor. -Immediate collision overlaps can be done with the :ref:`target_position` set to ``Vector3(0, 0, 0)`` and by calling :ref:`force_shapecast_update` within the same **physics frame**. This also helps to overcome some limitations of :ref:`Area3D` when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to :ref:`Area3D` nodes, and when using the signals creates unnecessary complexity. +Immediate collision overlaps can be done with the :ref:`target_position` set to ``Vector3(0, 0, 0)`` and by calling :ref:`force_shapecast_update` within the same physics frame. This helps to overcome some limitations of :ref:`Area3D` when used as an instantaneous detection area, as collision information isn't immediately available to it. -The node can detect multiple collision objects, but it's usually used to detect the first collision. - -\ **Note:** Shape casting is more computationally expensive compared to ray casting. +\ **Note:** Shape casting is more computationally expensive than ray casting. .. rst-class:: classref-reftable-group diff --git a/classes/class_signal.rst b/classes/class_signal.rst index 6553948b39e..b31edc6f54c 100644 --- a/classes/class_signal.rst +++ b/classes/class_signal.rst @@ -10,7 +10,7 @@ Signal ====== -Built-in type representing a signal defined in an object. +A built-in type representing a signal of an :ref:`Object`. .. rst-class:: classref-introduction-group diff --git a/classes/class_skeleton3d.rst b/classes/class_skeleton3d.rst index b06260a56d8..7537eb924d5 100644 --- a/classes/class_skeleton3d.rst +++ b/classes/class_skeleton3d.rst @@ -21,9 +21,9 @@ Description **Skeleton3D** provides an interface for managing a hierarchy of bones, including pose, rest and animation (see :ref:`Animation`). It can also use ragdoll physics. -The overall transform of a bone with respect to the skeleton is determined by the following hierarchical order: rest pose, custom pose and pose. +The overall transform of a bone with respect to the skeleton is determined by bone pose. Bone rest defines the initial transform of the bone pose. -Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it not the actual global/world transform of the bone. +Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it is not the actual global/world transform of the bone. To setup different types of inverse kinematics, consider using :ref:`SkeletonIK3D`, or add a custom IK implementation in :ref:`Node._process` as a child node. @@ -479,7 +479,7 @@ Returns the bone index which is the parent of the bone at ``bone_idx``. If -1, t :ref:`Transform3D` **get_bone_pose** **(** :ref:`int` bone_idx **)** |const| -Returns the pose transform of the specified bone. Pose is applied on top of the custom pose, which is applied on top the rest pose. +Returns the pose transform of the specified bone. .. rst-class:: classref-item-separator diff --git a/classes/class_slider.rst b/classes/class_slider.rst index 1c6e3aa5d64..789da27bf5f 100644 --- a/classes/class_slider.rst +++ b/classes/class_slider.rst @@ -14,16 +14,14 @@ Slider **Inherited By:** :ref:`HSlider`, :ref:`VSlider` -Base class for GUI sliders. +Abstract base class for sliders. .. rst-class:: classref-introduction-group Description ----------- -Base class for GUI sliders. - -\ **Note:** The :ref:`Range.changed` and :ref:`Range.value_changed` signals are part of the :ref:`Range` class which this class inherits from. +Abstract base class for sliders, used to adjust a value by moving a grabber along a horizontal or vertical axis. Sliders are :ref:`Range`-based controls. .. rst-class:: classref-reftable-group diff --git a/classes/class_sliderjoint3d.rst b/classes/class_sliderjoint3d.rst index 17273b4b4f2..db4b179811c 100644 --- a/classes/class_sliderjoint3d.rst +++ b/classes/class_sliderjoint3d.rst @@ -12,14 +12,14 @@ SliderJoint3D **Inherits:** :ref:`Joint3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Slider between two PhysicsBodies in 3D. +A physics joint that restricts the movement of a 3D physics body along an axis relative to another physics body. .. rst-class:: classref-introduction-group Description ----------- -Slides across the X axis of the pivot object. See also :ref:`Generic6DOFJoint3D`. +A physics joint that restricts the movement of a 3D physics body along an axis relative to another physics body. For example, Body A could be a :ref:`StaticBody3D` representing a piston base, while Body B could be a :ref:`RigidBody3D` representing the piston head, moving up and down. .. rst-class:: classref-reftable-group diff --git a/classes/class_softbody3d.rst b/classes/class_softbody3d.rst index dd2a95e179f..59f3d990542 100644 --- a/classes/class_softbody3d.rst +++ b/classes/class_softbody3d.rst @@ -12,16 +12,16 @@ SoftBody3D **Inherits:** :ref:`MeshInstance3D` **<** :ref:`GeometryInstance3D` **<** :ref:`VisualInstance3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -A soft mesh physics body. +A deformable 3D physics mesh. .. rst-class:: classref-introduction-group Description ----------- -A deformable physics body. Used to create elastic or deformable objects such as cloth, rubber, or other flexible materials. +A deformable 3D physics mesh. Used to create elastic or deformable objects such as cloth, rubber, or other flexible materials. -\ **Note:** There are many known bugs in **SoftBody3D**. Therefore, it's not recommended to use them for things that can affect gameplay (such as a player character made entirely out of soft bodies). +\ **Note:** There are many known bugs in **SoftBody3D**. Therefore, it's not recommended to use them for things that can affect gameplay (such as trampolines). .. rst-class:: classref-introduction-group diff --git a/classes/class_sphereshape3d.rst b/classes/class_sphereshape3d.rst index 4ea53c86d7b..ecd9f9b89e3 100644 --- a/classes/class_sphereshape3d.rst +++ b/classes/class_sphereshape3d.rst @@ -12,16 +12,16 @@ SphereShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Sphere shape resource for 3D collisions. +A 3D sphere shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -3D sphere shape to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. This shape is useful for modeling sphere-like 3D objects. +A 3D sphere shape, intended for use in physics. Usually used to provide a shape for a :ref:`CollisionShape3D`. -\ **Performance:** Being a primitive collision shape, **SphereShape3D** is the fastest collision shape to check collisions against, as it only requires a distance check with the shape's origin. +\ **Performance:** **SphereShape3D** is fast to check collisions against. It is faster than :ref:`BoxShape3D`, :ref:`CapsuleShape3D`, and :ref:`CylinderShape3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_spinbox.rst b/classes/class_spinbox.rst index ef3458bbb87..0b062341451 100644 --- a/classes/class_spinbox.rst +++ b/classes/class_spinbox.rst @@ -12,14 +12,14 @@ SpinBox **Inherits:** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Numerical input text field. +An input field for numbers. .. rst-class:: classref-introduction-group Description ----------- -SpinBox is a numerical input text field. It allows entering integers and floats. +**SpinBox** is a numerical input text field. It allows entering integers and floating point numbers. \ **Example:**\ diff --git a/classes/class_splitcontainer.rst b/classes/class_splitcontainer.rst index a669ac7076c..8d445357483 100644 --- a/classes/class_splitcontainer.rst +++ b/classes/class_splitcontainer.rst @@ -14,21 +14,21 @@ SplitContainer **Inherited By:** :ref:`HSplitContainer`, :ref:`VSplitContainer` -Container for splitting and adjusting. +A container that splits two child controls horizontally or vertically and provides a grabber for adjusting the split ratio. .. rst-class:: classref-introduction-group Description ----------- -Container for splitting two :ref:`Control`\ s vertically or horizontally, with a grabber that allows adjusting the split offset or ratio. +A container that accepts only two child controls, then arranges them horizontally or vertically and creates a divisor between them. The divisor can be dragged around to change the size relation between the child controls. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_springarm3d.rst b/classes/class_springarm3d.rst index 8eadd2d0650..98337e2dd4d 100644 --- a/classes/class_springarm3d.rst +++ b/classes/class_springarm3d.rst @@ -12,20 +12,14 @@ SpringArm3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -A helper node, mostly used in 3rd person cameras. +A 3D raycast that dynamically moves its children near the collision point. .. rst-class:: classref-introduction-group Description ----------- -The SpringArm3D node is a node that casts a ray (or collision shape) along its z axis and moves all its direct children to the collision point, minus a margin. - -The most common use case for this is to make a 3rd person camera that reacts to collisions in the environment. - -The SpringArm3D will either cast a ray, or if a shape is given, it will cast the shape in the direction of its z axis. - -If you use the SpringArm3D as a camera controller for your player, you might need to exclude the player's collider from the SpringArm3D's collision check. +**SpringArm3D** casts a ray or a shape along its Z axis and moves all its direct children to the collision point, with an optional margin. This is useful for 3rd person cameras that move closer to the player when inside a tight space (you may need to exclude the player's collider from the **SpringArm3D**'s collision check. .. rst-class:: classref-reftable-group diff --git a/classes/class_staticbody2d.rst b/classes/class_staticbody2d.rst index 9aff498a475..e1a7a9339e6 100644 --- a/classes/class_staticbody2d.rst +++ b/classes/class_staticbody2d.rst @@ -14,22 +14,18 @@ StaticBody2D **Inherited By:** :ref:`AnimatableBody2D` -Physics body for 2D physics which is static or moves only by script (without affecting other bodies on its path). Useful for floors and walls. +A 2D physics body that can't be moved by external forces. When moved manually, it doesn't affect other bodies in its path. .. rst-class:: classref-introduction-group Description ----------- -Static body for 2D physics. +A static 2D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, :ref:`AnimationPlayer`\ s (with :ref:`AnimationPlayer.playback_process_mode` set to ``ANIMATION_PROCESS_PHYSICS``), and :ref:`RemoteTransform2D`. -A static body is a simple body that doesn't move under physics simulation, i.e. it can't be moved by external forces or contacts but its transformation can still be updated manually by the user. It is ideal for implementing objects in the environment, such as walls or platforms. In contrast to :ref:`RigidBody2D`, it doesn't consume any CPU resources as long as they don't move. +When **StaticBody2D** is moved, it is teleported to its new position without affecting other physics bodies in its path. If this is not desired, use :ref:`AnimatableBody2D` instead. -They have extra functionalities to move and affect other bodies: - -\ **Static transform change:** Static bodies *can* be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path. Use :ref:`AnimatableBody2D` instead of **StaticBody2D** if you need a moving static body that affects other bodies on its path. - -\ **Constant velocity:** When :ref:`constant_linear_velocity` or :ref:`constant_angular_velocity` is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels. +\ **StaticBody2D** is useful for completely static objects like floors and walls, as well as moving surfaces like conveyor belts and circular revolving platforms (by using :ref:`constant_linear_velocity` and :ref:`constant_angular_velocity`). .. rst-class:: classref-reftable-group diff --git a/classes/class_staticbody3d.rst b/classes/class_staticbody3d.rst index 1ab6d2d11ce..3e6ddc1734e 100644 --- a/classes/class_staticbody3d.rst +++ b/classes/class_staticbody3d.rst @@ -14,24 +14,18 @@ StaticBody3D **Inherited By:** :ref:`AnimatableBody3D` -Physics body for 3D physics which is static or moves only by script (without affecting other bodies on its path). Useful for floors and walls. +A 3D physics body that can't be moved by external forces. When moved manually, it doesn't affect other bodies in its path. .. rst-class:: classref-introduction-group Description ----------- -Static body for 3D physics. +A static 3D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, :ref:`AnimationPlayer`\ s (with :ref:`AnimationPlayer.playback_process_mode` set to ``ANIMATION_PROCESS_PHYSICS``), and :ref:`RemoteTransform3D`. -A static body is a simple body that doesn't move under physics simulation, i.e. it can't be moved by external forces or contacts but its transformation can still be updated manually by the user. It is ideal for implementing objects in the environment, such as walls or platforms. In contrast to :ref:`RigidBody3D`, it doesn't consume any CPU resources as long as they don't move. +When **StaticBody3D** is moved, it is teleported to its new position without affecting other physics bodies in its path. If this is not desired, use :ref:`AnimatableBody3D` instead. -They have extra functionalities to move and affect other bodies: - -\ **Static transform change:** Static bodies *can* be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path. Use :ref:`AnimatableBody3D` instead of **StaticBody3D** if you need a moving static body that affects other bodies on its path. - -\ **Constant velocity:** When :ref:`constant_linear_velocity` or :ref:`constant_angular_velocity` is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels. - -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +\ **StaticBody3D** is useful for completely static objects like floors and walls, as well as moving surfaces like conveyor belts and circular revolving platforms (by using :ref:`constant_linear_velocity` and :ref:`constant_angular_velocity`). .. rst-class:: classref-introduction-group diff --git a/classes/class_streampeer.rst b/classes/class_streampeer.rst index b99b7a942dd..ff13e035b5f 100644 --- a/classes/class_streampeer.rst +++ b/classes/class_streampeer.rst @@ -14,14 +14,14 @@ StreamPeer **Inherited By:** :ref:`StreamPeerBuffer`, :ref:`StreamPeerExtension`, :ref:`StreamPeerGZIP`, :ref:`StreamPeerTCP`, :ref:`StreamPeerTLS` -Abstraction and base class for stream-based protocols. +Abstract base class for interacting with streams. .. rst-class:: classref-introduction-group Description ----------- -StreamPeer is an abstraction and base class for stream-based protocols (such as TCP). It provides an API for sending and receiving data through streams as raw data or strings. +StreamPeer is an abstract base class mostly used for stream-based protocols (such as TCP). It provides an API for sending and receiving data through streams as raw data or strings. \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. @@ -314,7 +314,7 @@ Gets an unsigned 64-bit value from the stream. :ref:`String` **get_utf8_string** **(** :ref:`int` bytes=-1 **)** -Gets an UTF-8 string with byte-length ``bytes`` from the stream (this decodes the string sent as UTF-8). If ``bytes`` is negative (default) the length will be read from the stream using the reverse process of :ref:`put_utf8_string`. +Gets a UTF-8 string with byte-length ``bytes`` from the stream (this decodes the string sent as UTF-8). If ``bytes`` is negative (default) the length will be read from the stream using the reverse process of :ref:`put_utf8_string`. .. rst-class:: classref-item-separator @@ -515,7 +515,7 @@ void **put_utf8_string** **(** :ref:`String` value **)** Puts a zero-terminated UTF-8 string into the stream prepended by a 32 bits unsigned integer representing its size. -\ **Note:** To put an UTF-8 string without prepending its size, you can use :ref:`put_data`: +\ **Note:** To put a UTF-8 string without prepending its size, you can use :ref:`put_data`: .. tabs:: diff --git a/classes/class_streampeerbuffer.rst b/classes/class_streampeerbuffer.rst index e0749731cc3..f2e8d74e4fd 100644 --- a/classes/class_streampeerbuffer.rst +++ b/classes/class_streampeerbuffer.rst @@ -12,14 +12,14 @@ StreamPeerBuffer **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -Data buffer stream peer. +A stream peer used to handle binary data streams. .. rst-class:: classref-introduction-group Description ----------- -Data buffer stream peer that uses a byte array as the stream. This object can be used to handle binary data from network sessions. To handle binary data stored in files, :ref:`FileAccess` can be used directly. +A data buffer stream peer that uses a byte array as the stream. This object can be used to handle binary data from network sessions. To handle binary data stored in files, :ref:`FileAccess` can be used directly. A **StreamPeerBuffer** object keeps an internal cursor which is the offset in bytes to the start of the buffer. Get and put operations are performed at the cursor position and will move the cursor accordingly. diff --git a/classes/class_streampeergzip.rst b/classes/class_streampeergzip.rst index 87ac4dbdeb6..39954a0b24d 100644 --- a/classes/class_streampeergzip.rst +++ b/classes/class_streampeergzip.rst @@ -12,14 +12,14 @@ StreamPeerGZIP **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -Stream peer handling GZIP and deflate compression/decompresison. +A stream peer that handles GZIP and deflate compression/decompression. .. rst-class:: classref-introduction-group Description ----------- -This class allows to compress or decompress data using GZIP/deflate in a streaming fashion. This is particularly useful when compressing or decompressing files that has to be sent through the network without having to allocate them all in memory. +This class allows to compress or decompress data using GZIP/deflate in a streaming fashion. This is particularly useful when compressing or decompressing files that have to be sent through the network without needing to allocate them all in memory. After starting the stream via :ref:`start_compression` (or :ref:`start_decompression`), calling :ref:`StreamPeer.put_partial_data` on this stream will compress (or decompress) the data, writing it to the internal buffer. Calling :ref:`StreamPeer.get_available_bytes` will return the pending bytes in the internal buffer, and :ref:`StreamPeer.get_partial_data` will retrieve the compressed (or decompressed) bytes from it. When the stream is over, you must call :ref:`finish` to ensure the internal buffer is properly flushed (make sure to call :ref:`StreamPeer.get_available_bytes` on last time to check if more data needs to be read after that). diff --git a/classes/class_streampeertcp.rst b/classes/class_streampeertcp.rst index a7c502b171d..48d316aa891 100644 --- a/classes/class_streampeertcp.rst +++ b/classes/class_streampeertcp.rst @@ -12,14 +12,14 @@ StreamPeerTCP **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -TCP stream peer. +A stream peer that handles TCP connections. .. rst-class:: classref-introduction-group Description ----------- -TCP stream peer. This object can be used to connect to TCP servers, or also is returned by a TCP server. +A stream peer that handles TCP connections. This object can be used to connect to TCP servers, or also is returned by a TCP server. \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. diff --git a/classes/class_streampeertls.rst b/classes/class_streampeertls.rst index ba9f6738b26..d4203174517 100644 --- a/classes/class_streampeertls.rst +++ b/classes/class_streampeertls.rst @@ -12,14 +12,14 @@ StreamPeerTLS **Inherits:** :ref:`StreamPeer` **<** :ref:`RefCounted` **<** :ref:`Object` -TLS stream peer. +A stream peer that handles TLS connections. .. rst-class:: classref-introduction-group Description ----------- -TLS stream peer. This object can be used to connect to a TLS server or accept a single TLS client connection. +A stream peer that handles TLS connections. This object can be used to connect to a TLS server or accept a single TLS client connection. \ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. diff --git a/classes/class_string.rst b/classes/class_string.rst index 8ecc1efa4a8..4f4491b58fa 100644 --- a/classes/class_string.rst +++ b/classes/class_string.rst @@ -10,7 +10,7 @@ String ====== -Built-in string Variant type. +A built-in type for strings. .. rst-class:: classref-introduction-group @@ -21,7 +21,7 @@ This is the built-in string Variant type (and the one used by GDScript). Strings Some string methods have corresponding variations. Variations suffixed with ``n`` (:ref:`countn`, :ref:`findn`, :ref:`replacen`, etc.) are **case-insensitive** (they make no distinction between uppercase and lowercase letters). Method variations prefixed with ``r`` (:ref:`rfind`, :ref:`rsplit`, etc.) are reversed, and start from the end of the string, instead of the beginning. -\ **Note:** In a boolean context, a string will evaluate to ``false`` if it is empty (``""``). Otherwise, a string will always evaluate to ``true``. +\ **Note:** In a boolean context, a string will evaluate to ``false`` if it is empty (``""``). Otherwise, a string will always evaluate to ``true``. The ``not`` operator cannot be used. Instead, :ref:`is_empty` should be used to check for empty strings. .. rst-class:: classref-introduction-group diff --git a/classes/class_stringname.rst b/classes/class_stringname.rst index e1630dfe864..1024e40f3bd 100644 --- a/classes/class_stringname.rst +++ b/classes/class_stringname.rst @@ -10,22 +10,22 @@ StringName ========== -An optimized string type for unique names. +A built-in type for unique strings. .. rst-class:: classref-introduction-group Description ----------- -**StringName**\ s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). **StringName** ensures that only one instance of a given name exists (so two **StringName**\ s with the same value are the same object). Comparing them is much faster than with regular :ref:`String`\ s, because only the pointers are compared, not the whole strings. +**StringName**\ s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). Two **StringName**\ s with the same value are the same object. Comparing them is extremely fast compared to regular :ref:`String`\ s. You will usually just pass a :ref:`String` to methods expecting a **StringName** and it will be automatically converted, but you may occasionally want to construct a **StringName** ahead of time with the **StringName** constructor or, in GDScript, the literal syntax ``&"example"``. -See also :ref:`NodePath`, which is a similar concept specifically designed to store pre-parsed node paths. +See also :ref:`NodePath`, which is a similar concept specifically designed to store pre-parsed scene tree paths. -Some string methods have corresponding variations. Variations suffixed with ``n`` (:ref:`countn`, :ref:`findn`, :ref:`replacen`, etc.) are **case-insensitive** (they make no distinction between uppercase and lowercase letters). Method variations prefixed with ``r`` (:ref:`rfind`, :ref:`rsplit`, etc.) are reversed, and start from the end of the string, instead of the beginning. +All of :ref:`String`'s methods are available in this class too. They convert the **StringName** into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired. -\ **Note:** In a boolean context, a **StringName** will evaluate to ``false`` if it is empty (``StringName("")``). Otherwise, a **StringName** will always evaluate to ``true``. +\ **Note:** In a boolean context, a **StringName** will evaluate to ``false`` if it is empty (``StringName("")``). Otherwise, a **StringName** will always evaluate to ``true``. The ``not`` operator cannot be used. Instead, :ref:`is_empty` should be used to check for empty **StringName**\ s. .. rst-class:: classref-reftable-group diff --git a/classes/class_stylebox.rst b/classes/class_stylebox.rst index d18e7e5e98f..db4e43a39e6 100644 --- a/classes/class_stylebox.rst +++ b/classes/class_stylebox.rst @@ -14,16 +14,16 @@ StyleBox **Inherited By:** :ref:`StyleBoxEmpty`, :ref:`StyleBoxFlat`, :ref:`StyleBoxLine`, :ref:`StyleBoxTexture` -Base class for drawing stylized boxes for the UI. +Abstract base class for defining stylized boxes for UI elements. .. rst-class:: classref-introduction-group Description ----------- -StyleBox is :ref:`Resource` that provides an abstract base class for drawing stylized boxes for the UI. StyleBoxes are used for drawing the styles of buttons, line edit backgrounds, tree backgrounds, etc. and also for testing a transparency mask for pointer signals. If mask test fails on a StyleBox assigned as mask to a control, clicks and motion signals will go through it to the one below. +**StyleBox** is an abstract base class for drawing stylized boxes for UI elements. It is used for panels, buttons, :ref:`LineEdit` backgrounds, :ref:`Tree` backgrounds, etc. and also for testing a transparency mask for pointer signals. If mask test fails on a **StyleBox** assigned as mask to a control, clicks and motion signals will go through it to the one below. -\ **Note:** For children of :ref:`Control` that have *Theme Properties*, the ``focus`` **StyleBox** is displayed over the ``normal``, ``hover`` or ``pressed`` **StyleBox**. This makes the ``focus`` **StyleBox** more reusable across different nodes. +\ **Note:** For control nodes that have *Theme Properties*, the ``focus`` **StyleBox** is displayed over the ``normal``, ``hover`` or ``pressed`` **StyleBox**. This makes the ``focus`` **StyleBox** more reusable across different nodes. .. rst-class:: classref-reftable-group diff --git a/classes/class_styleboxempty.rst b/classes/class_styleboxempty.rst index e9eb75427b2..4ffdb57530d 100644 --- a/classes/class_styleboxempty.rst +++ b/classes/class_styleboxempty.rst @@ -12,14 +12,14 @@ StyleBoxEmpty **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Empty stylebox (does not display anything). +An empty :ref:`StyleBox` (does not display anything). .. rst-class:: classref-introduction-group Description ----------- -Empty stylebox (really does not display anything). +An empty :ref:`StyleBox` that can be used to display nothing instead of the default style (e.g. it can "disable" ``focus`` styles). .. |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_styleboxflat.rst b/classes/class_styleboxflat.rst index 3e673688d8e..2bf8decb108 100644 --- a/classes/class_styleboxflat.rst +++ b/classes/class_styleboxflat.rst @@ -12,22 +12,14 @@ StyleBoxFlat **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Customizable :ref:`StyleBox` with a given set of parameters (no texture required). +A customizable :ref:`StyleBox` that doesn't use a texture. .. rst-class:: classref-introduction-group Description ----------- -This :ref:`StyleBox` can be used to achieve all kinds of looks without the need of a texture. The following properties are customizable: - -- Color - -- Border width (individual width for each border) - -- Rounded corners (individual radius for each corner) - -- Shadow (with blur and offset) +By configuring various properties of this style box, you can achieve many common looks without the need of a texture. This includes optionally rounded borders, antialiasing, shadows, and skew. Setting corner radius to high values is allowed. As soon as corners overlap, the stylebox will switch to a relative system. diff --git a/classes/class_styleboxline.rst b/classes/class_styleboxline.rst index 3d942771a96..eeb3aef1487 100644 --- a/classes/class_styleboxline.rst +++ b/classes/class_styleboxline.rst @@ -12,14 +12,14 @@ StyleBoxLine **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -:ref:`StyleBox` that displays a single line. +A :ref:`StyleBox` that displays a single line of a given color and thickness. .. rst-class:: classref-introduction-group Description ----------- -:ref:`StyleBox` that displays a single line of a given color and thickness. It can be used to draw things like separators. +A :ref:`StyleBox` that displays a single line of a given color and thickness. The line can be either horizontal or vertical. Useful for separators. .. rst-class:: classref-reftable-group diff --git a/classes/class_styleboxtexture.rst b/classes/class_styleboxtexture.rst index daf6929c373..e8697dbd364 100644 --- a/classes/class_styleboxtexture.rst +++ b/classes/class_styleboxtexture.rst @@ -12,14 +12,14 @@ StyleBoxTexture **Inherits:** :ref:`StyleBox` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Texture-based nine-patch :ref:`StyleBox`. +A texture-based nine-patch :ref:`StyleBox`. .. rst-class:: classref-introduction-group Description ----------- -Texture-based nine-patch :ref:`StyleBox`, in a way similar to :ref:`NinePatchRect`. This stylebox performs a 3×3 scaling of a texture, where only the center cell is fully stretched. This makes it possible to design bordered styles regardless of the stylebox's size. +A texture-based nine-patch :ref:`StyleBox`, in a way similar to :ref:`NinePatchRect`. This stylebox performs a 3×3 scaling of a texture, where only the center cell is fully stretched. This makes it possible to design bordered styles regardless of the stylebox's size. .. rst-class:: classref-reftable-group diff --git a/classes/class_subviewport.rst b/classes/class_subviewport.rst index c5a7b22169d..0977be29c90 100644 --- a/classes/class_subviewport.rst +++ b/classes/class_subviewport.rst @@ -12,14 +12,16 @@ SubViewport **Inherits:** :ref:`Viewport` **<** :ref:`Node` **<** :ref:`Object` -Creates a sub-view into the screen. +An interface to a game world that doesn't create a window or draw to the screen directly. .. rst-class:: classref-introduction-group Description ----------- -**SubViewport** is a :ref:`Viewport` that isn't a :ref:`Window`, i.e. it doesn't draw anything by itself. To display something, **SubViewport**'s :ref:`size` must be non-zero and it should be either put inside a :ref:`SubViewportContainer` or assigned to a :ref:`ViewportTexture`. +**SubViewport** Isolates a rectangular region of a scene to be displayed independently. This can be used, for example, to display UI in 3D space. + +\ **Note:** **SubViewport** is a :ref:`Viewport` that isn't a :ref:`Window`, i.e. it doesn't draw anything by itself. To display anything, **SubViewport** must have a non-zero size and be either put inside a :ref:`SubViewportContainer` or assigned to a :ref:`ViewportTexture`. .. rst-class:: classref-introduction-group diff --git a/classes/class_subviewportcontainer.rst b/classes/class_subviewportcontainer.rst index 1f0d03f1d5a..664f4b2bcf0 100644 --- a/classes/class_subviewportcontainer.rst +++ b/classes/class_subviewportcontainer.rst @@ -12,18 +12,18 @@ SubViewportContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control for holding :ref:`SubViewport`\ s. +A container used for displaying the contents of a :ref:`SubViewport`. .. rst-class:: classref-introduction-group Description ----------- -A :ref:`Container` node that holds a :ref:`SubViewport`. It uses the :ref:`SubViewport`'s size as minimum size, unless :ref:`stretch` is enabled. +A container that displays the contents of underlying :ref:`SubViewport` child nodes. It uses the combined size of the :ref:`SubViewport`\ s as minimum size, unless :ref:`stretch` is enabled. -\ **Note:** Changing a SubViewportContainer's :ref:`Control.scale` will cause its contents to appear distorted. To change its visual size without causing distortion, adjust the node's margins instead (if it's not already in a container). +\ **Note:** Changing a **SubViewportContainer**'s :ref:`Control.scale` will cause its contents to appear distorted. To change its visual size without causing distortion, adjust the node's margins instead (if it's not already in a container). -\ **Note:** The SubViewportContainer forwards mouse-enter and mouse-exit notifications to its sub-viewports. +\ **Note:** The **SubViewportContainer** forwards mouse-enter and mouse-exit notifications to its sub-viewports. .. rst-class:: classref-reftable-group diff --git a/classes/class_surfacetool.rst b/classes/class_surfacetool.rst index 4d09625b6d6..421542d7bef 100644 --- a/classes/class_surfacetool.rst +++ b/classes/class_surfacetool.rst @@ -37,7 +37,7 @@ The **SurfaceTool** is used to construct a :ref:`Mesh` by specifying var st = new SurfaceTool(); st.Begin(Mesh.PrimitiveType.Triangles); st.SetColor(new Color(1, 0, 0)); - st.SetUv(new Vector2(0, 0)); + st.SetUV(new Vector2(0, 0)); st.AddVertex(new Vector3(0, 0, 0)); @@ -611,7 +611,7 @@ void **set_smooth_group** **(** :ref:`int` index **)** Specifies the smooth group to use for the *next* vertex. If this is never called, all vertices will have the default smooth group of ``0`` and will be smoothed with adjacent vertices of the same group. To produce a mesh with flat normals, set the smooth group to ``-1``. -\ **Note:** This function actually takes an ``uint32_t``, so C# users should use ``uint32.MaxValue`` instead of ``-1`` to produce a mesh with flat normals. +\ **Note:** This function actually takes a ``uint32_t``, so C# users should use ``uint32.MaxValue`` instead of ``-1`` to produce a mesh with flat normals. .. rst-class:: classref-item-separator diff --git a/classes/class_syntaxhighlighter.rst b/classes/class_syntaxhighlighter.rst index bf034614887..d225988e073 100644 --- a/classes/class_syntaxhighlighter.rst +++ b/classes/class_syntaxhighlighter.rst @@ -14,18 +14,16 @@ SyntaxHighlighter **Inherited By:** :ref:`CodeHighlighter`, :ref:`EditorSyntaxHighlighter` -Base Syntax highlighter resource for :ref:`TextEdit`. +Base class for syntax highlighters. Provides syntax highlighting data to a :ref:`TextEdit`. .. rst-class:: classref-introduction-group Description ----------- -Base syntax highlighter resource all syntax highlighters extend from, provides syntax highlighting data to :ref:`TextEdit`. +Base class for syntax highlighters. Provides syntax highlighting data to a :ref:`TextEdit`. The associated :ref:`TextEdit` will call into the **SyntaxHighlighter** on an as-needed basis. -The associated :ref:`TextEdit` node will call into the **SyntaxHighlighter** on an as-needed basis. - -\ **Note:** Each Syntax highlighter instance should not be shared across multiple :ref:`TextEdit` nodes. +\ **Note:** A **SyntaxHighlighter** instance should not be used across multiple :ref:`TextEdit` nodes. .. rst-class:: classref-reftable-group diff --git a/classes/class_systemfont.rst b/classes/class_systemfont.rst index a39924a8e1d..84fe61aac85 100644 --- a/classes/class_systemfont.rst +++ b/classes/class_systemfont.rst @@ -12,9 +12,7 @@ SystemFont **Inherits:** :ref:`Font` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Font loaded from a system font. - -\ **Note:** This class is implemented on iOS, Linux, macOS and Windows, on other platforms it will fallback to default theme font. +A font loaded from a system font. Falls back to a default theme font if not implemented on the host OS. .. rst-class:: classref-introduction-group @@ -29,6 +27,8 @@ The returned font might be part of a font collection or be a variable font with You can create :ref:`FontVariation` of the system font for fine control over its features. +\ **Note:** This class is implemented on iOS, Linux, macOS and Windows, on other platforms it will fallback to default theme font. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_tabbar.rst b/classes/class_tabbar.rst index 999e57553a8..96f02937d23 100644 --- a/classes/class_tabbar.rst +++ b/classes/class_tabbar.rst @@ -12,14 +12,14 @@ TabBar **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tab bar control. +A control that provides a horizontal bar with tabs. .. rst-class:: classref-introduction-group Description ----------- -Simple tabs control, similar to :ref:`TabContainer` but is only in charge of drawing tabs, not interacting with children. +A control that provides a horizontal bar with tabs. Similar to :ref:`TabContainer` but is only in charge of drawing tabs, not interacting with children. .. rst-class:: classref-reftable-group diff --git a/classes/class_tabcontainer.rst b/classes/class_tabcontainer.rst index 93ef6a925ff..0ffe1c76992 100644 --- a/classes/class_tabcontainer.rst +++ b/classes/class_tabcontainer.rst @@ -12,25 +12,23 @@ TabContainer **Inherits:** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Tabbed container. +A container that creates a tab for each child control, displaying only the active tab's control. .. rst-class:: classref-introduction-group Description ----------- -Arranges :ref:`Control` children into a tabbed view, creating a tab for each one. The active tab's corresponding :ref:`Control` has its ``visible`` property set to ``true``, and all other children's to ``false``. +Arranges child controls into a tabbed view, creating a tab for each one. The active tab's corresponding control is made visible, while all other child controls are hidden. Ignores non-control children. -Ignores non-:ref:`Control` children. - -\ **Note:** The drawing of the clickable tabs themselves is handled by this node. Adding :ref:`TabBar`\ s as children is not needed. +\ **Note:** The drawing of the clickable tabs is handled by this node; :ref:`TabBar` is not needed. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_textedit.rst b/classes/class_textedit.rst index 30d745d0f6b..9697448ecee 100644 --- a/classes/class_textedit.rst +++ b/classes/class_textedit.rst @@ -14,14 +14,14 @@ TextEdit **Inherited By:** :ref:`CodeEdit` -Multiline text editing control. +A multiline text editor. .. rst-class:: classref-introduction-group Description ----------- -TextEdit is meant for editing large, multiline text. It also has facilities for editing code, such as syntax highlighting support and multiple levels of undo/redo. +A multiline text editor. It also has limited facilities for editing code, such as syntax highlighting support. For more advanced facilities for editing code, see :ref:`CodeEdit`. \ **Note:** Most viewport, caret and edit methods contain a ``caret_index`` argument for :ref:`caret_multiple` support. The argument should be one of the following: ``-1`` for all carets, ``0`` for the main caret, or greater than ``0`` for secondary carets. diff --git a/classes/class_textline.rst b/classes/class_textline.rst index 0a6acca8214..5876466ca6c 100644 --- a/classes/class_textline.rst +++ b/classes/class_textline.rst @@ -19,7 +19,7 @@ Holds a line of text. Description ----------- -Abstraction over :ref:`TextServer` for handling single line of text. +Abstraction over :ref:`TextServer` for handling a single line of text. .. rst-class:: classref-reftable-group diff --git a/classes/class_textparagraph.rst b/classes/class_textparagraph.rst index 744fba7717a..4e70e9f294e 100644 --- a/classes/class_textparagraph.rst +++ b/classes/class_textparagraph.rst @@ -19,7 +19,7 @@ Holds a paragraph of text. Description ----------- -Abstraction over :ref:`TextServer` for handling paragraph of text. +Abstraction over :ref:`TextServer` for handling a single paragraph of text. .. rst-class:: classref-reftable-group diff --git a/classes/class_textserver.rst b/classes/class_textserver.rst index 8329e941fd7..ba217d3747f 100644 --- a/classes/class_textserver.rst +++ b/classes/class_textserver.rst @@ -14,14 +14,14 @@ TextServer **Inherited By:** :ref:`TextServerExtension` -Interface for the fonts and complex text layouts. +A server interface for font management and text rendering. .. rst-class:: classref-introduction-group Description ----------- -**TextServer** is the API backend for managing fonts, and rendering complex text. +**TextServer** is the API backend for managing fonts and rendering text. .. rst-class:: classref-reftable-group @@ -1475,7 +1475,7 @@ Method Descriptions :ref:`RID` **create_font** **(** **)** -Creates new, empty font cache entry resource. To free the resulting resource, use :ref:`free_rid` method. +Creates a new, empty font cache entry resource. To free the resulting resource, use the :ref:`free_rid` method. .. rst-class:: classref-item-separator diff --git a/classes/class_textserveradvanced.rst b/classes/class_textserveradvanced.rst index 3615e4bbdf4..476af3eabfc 100644 --- a/classes/class_textserveradvanced.rst +++ b/classes/class_textserveradvanced.rst @@ -12,7 +12,14 @@ TextServerAdvanced **Inherits:** :ref:`TextServerExtension` **<** :ref:`TextServer` **<** :ref:`RefCounted` **<** :ref:`Object` -Text Server using HarfBuzz, ICU and SIL Graphite to support BiDi, complex text layouts and contextual OpenType features. +An advanced text server with support for BiDi, complex text layout, and contextual OpenType features. Used in Godot by default. + +.. rst-class:: classref-introduction-group + +Description +----------- + +An implementation of :ref:`TextServer` that uses HarfBuzz, ICU and SIL Graphite to support BiDi, complex text layouts and contextual OpenType features. This is Godot's default primary :ref:`TextServer` interface. .. |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_textserverextension.rst b/classes/class_textserverextension.rst index 88c2b8c4dcd..1d68dc01d38 100644 --- a/classes/class_textserverextension.rst +++ b/classes/class_textserverextension.rst @@ -14,14 +14,14 @@ TextServerExtension **Inherited By:** :ref:`TextServerAdvanced`, :ref:`TextServerDummy`, :ref:`TextServerFallback` -Base class for TextServer custom implementations (plugins). +Base class for custom :ref:`TextServer` implementations (plugins). .. rst-class:: classref-introduction-group Description ----------- -External TextServer implementations should inherit from this class. +External :ref:`TextServer` implementations should inherit from this class. .. rst-class:: classref-reftable-group diff --git a/classes/class_textserverfallback.rst b/classes/class_textserverfallback.rst index 4d6dc1cbea2..2e1c914b97c 100644 --- a/classes/class_textserverfallback.rst +++ b/classes/class_textserverfallback.rst @@ -12,7 +12,16 @@ TextServerFallback **Inherits:** :ref:`TextServerExtension` **<** :ref:`TextServer` **<** :ref:`RefCounted` **<** :ref:`Object` -Fallback implementation of the Text Server, without BiDi and complex text layout support. +A fallback implementation of Godot's text server, without support for BiDi and complex text layout. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A fallback implementation of Godot's text server. This fallback is faster than :ref:`TextServerAdvanced` for processing a lot of text, but it does not support BiDi and complex text layout. + +\ **Note:** This text server is not part of official Godot binaries. If you want to use it, compile the engine with the option ``module_text_server_fb_enabled=yes``. .. |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_textservermanager.rst b/classes/class_textservermanager.rst index 378e1fd8638..65dcdc0c514 100644 --- a/classes/class_textservermanager.rst +++ b/classes/class_textservermanager.rst @@ -12,14 +12,14 @@ TextServerManager **Inherits:** :ref:`Object` -Manager for the font and complex text layout servers. +A singleton for managing :ref:`TextServer` implementations. .. rst-class:: classref-introduction-group Description ----------- -**TextServerManager** is the API backend for loading, enumeration and switching :ref:`TextServer`\ s. +**TextServerManager** is the API backend for loading, enumerating, and switching :ref:`TextServer`\ s. \ **Note:** Switching text server at runtime is possible, but will invalidate all fonts and text buffers. Make sure to unload all controls, fonts, and themes before doing so. @@ -93,7 +93,7 @@ Method Descriptions void **add_interface** **(** :ref:`TextServer` interface **)** -Registers an :ref:`TextServer` interface. +Registers a :ref:`TextServer` interface. .. rst-class:: classref-item-separator @@ -105,7 +105,7 @@ Registers an :ref:`TextServer` interface. :ref:`TextServer` **find_interface** **(** :ref:`String` name **)** |const| -Finds an interface by its name. +Finds an interface by its ``name``. .. rst-class:: classref-item-separator @@ -141,7 +141,7 @@ Returns the number of interfaces currently registered. :ref:`Dictionary[]` **get_interfaces** **(** **)** |const| -Returns a list of available interfaces the index and name of each interface. +Returns a list of available interfaces, with the index and name of each interface. .. rst-class:: classref-item-separator @@ -165,7 +165,7 @@ Returns the primary :ref:`TextServer` interface currently in u void **remove_interface** **(** :ref:`TextServer` interface **)** -Removes interface. All fonts and shaped text caches should be freed before removing interface. +Removes an interface. All fonts and shaped text caches should be freed before removing an interface. .. rst-class:: classref-item-separator diff --git a/classes/class_texturebutton.rst b/classes/class_texturebutton.rst index 465845e925f..2c07f18d937 100644 --- a/classes/class_texturebutton.rst +++ b/classes/class_texturebutton.rst @@ -289,7 +289,7 @@ Texture to display when the mouse hovers the node. - void **set_texture_normal** **(** :ref:`Texture2D` value **)** - :ref:`Texture2D` **get_texture_normal** **(** **)** -Texture to display by default, when the node is **not** in the disabled, focused, hover or pressed state. +Texture to display by default, when the node is **not** in the disabled, hover or pressed state. This texture is still displayed in the focused state, with :ref:`texture_focused` drawn on top. .. rst-class:: classref-item-separator diff --git a/classes/class_texturerect.rst b/classes/class_texturerect.rst index ae93fb0ed06..cd450e2b32e 100644 --- a/classes/class_texturerect.rst +++ b/classes/class_texturerect.rst @@ -12,14 +12,14 @@ TextureRect **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control for drawing textures. +A control that displays a texture. .. rst-class:: classref-introduction-group Description ----------- -Used to draw icons and sprites in a user interface. The texture's placement can be controlled with the :ref:`stretch_mode` property. It can scale, tile, or stay centered inside its bounding rectangle. +A control that displays a texture, for example an icon inside a GUI. The texture's placement can be controlled with the :ref:`stretch_mode` property. It can scale, tile, or stay centered inside its bounding rectangle. .. rst-class:: classref-introduction-group diff --git a/classes/class_theme.rst b/classes/class_theme.rst index 0e6182e14d8..d142d12b41d 100644 --- a/classes/class_theme.rst +++ b/classes/class_theme.rst @@ -12,14 +12,14 @@ Theme **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Theme resource for styling/skinning :ref:`Control`\ s and :ref:`Window`\ s. +A resource used for styling/skinning :ref:`Control`\ s and :ref:`Window`\ s. .. rst-class:: classref-introduction-group Description ----------- -A theme resource is used for styling/skinning :ref:`Control` and :ref:`Window` nodes. While individual controls can be styled using their local theme overrides (see :ref:`Control.add_theme_color_override`), theme resources allow you to store and apply the same settings between all controls sharing the same type (e.g. style all :ref:`Button`\ s the same). One theme resource can be used for the entire project, but you can also set a separate theme resource to a branch of control nodes. A theme resources assigned to a control node applies to the control itself, as well as all of its direct and indirect children (as long as a chain of controls is uninterrupted). +A resource used for styling/skinning :ref:`Control` and :ref:`Window` nodes. While individual controls can be styled using their local theme overrides (see :ref:`Control.add_theme_color_override`), theme resources allow you to store and apply the same settings across all controls sharing the same type (e.g. style all :ref:`Button`\ s the same). One theme resource can be used for the entire project, but you can also set a separate theme resource to a branch of control nodes. A theme resource assigned to a control applies to the control itself, as well as all of its direct and indirect children (as long as a chain of controls is uninterrupted). Use :ref:`ProjectSettings.gui/theme/custom` to set up a project-scope theme that will be available to every control in your project. diff --git a/classes/class_themedb.rst b/classes/class_themedb.rst index 7bc3472eae1..552dfe02f69 100644 --- a/classes/class_themedb.rst +++ b/classes/class_themedb.rst @@ -12,14 +12,14 @@ ThemeDB **Inherits:** :ref:`Object` -An engine singleton providing access to static :ref:`Theme` information, such as default and project theme, and fallback values. +A singleton that provides access to static information about :ref:`Theme` resources used by the engine and by your project. .. rst-class:: classref-introduction-group Description ----------- -This engine singleton provides access to static information about :ref:`Theme` resources used by the engine and by your projects. You can fetch the default engine theme, as well as your project configured theme. +This singleton provides access to static information about :ref:`Theme` resources used by the engine and by your projects. You can fetch the default engine theme, as well as your project configured theme. \ **ThemeDB** also contains fallback values for theme properties. diff --git a/classes/class_thread.rst b/classes/class_thread.rst index 175c80e7565..263ce3a284c 100644 --- a/classes/class_thread.rst +++ b/classes/class_thread.rst @@ -25,7 +25,7 @@ A unit of execution in a process. Can run methods on :ref:`Object` \ **Warning:**\ -To guarantee that the operating system is able to perform proper cleanup (no crashes, no deadlocks), these conditions must be met by the time a **Thread**'s reference count reaches zero and therefore it is destroyed: +To ensure proper cleanup without crashes or deadlocks, when a **Thread**'s reference count reaches zero and it is therefore destroyed, the following conditions must be met: - It must not have any :ref:`Mutex` objects locked. diff --git a/classes/class_time.rst b/classes/class_time.rst index 2119273df8e..9fc14a24988 100644 --- a/classes/class_time.rst +++ b/classes/class_time.rst @@ -12,7 +12,7 @@ Time **Inherits:** :ref:`Object` -Time singleton for working with time. +A singleton for working with time data. .. rst-class:: classref-introduction-group diff --git a/classes/class_transform2d.rst b/classes/class_transform2d.rst index 0c5a8145f4d..7fb58542d2e 100644 --- a/classes/class_transform2d.rst +++ b/classes/class_transform2d.rst @@ -10,14 +10,14 @@ Transform2D =========== -2D transformation (2×3 matrix). +A 2×3 matrix representing a 2D transformation. .. rst-class:: classref-introduction-group Description ----------- -2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, or scaling. It consists of three :ref:`Vector2` values: :ref:`x`, :ref:`y`, and the :ref:`origin`. +A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three :ref:`Vector2` values: :ref:`x`, :ref:`y`, and the :ref:`origin`. For more information, read the "Matrices and transforms" documentation article. diff --git a/classes/class_transform3d.rst b/classes/class_transform3d.rst index 2965cc7b00b..053b61d7b26 100644 --- a/classes/class_transform3d.rst +++ b/classes/class_transform3d.rst @@ -10,14 +10,14 @@ Transform3D =========== -3D transformation (3×4 matrix). +A 3×4 matrix representing a 3D transformation. .. rst-class:: classref-introduction-group Description ----------- -3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, or scaling. It consists of a :ref:`basis` (first 3 columns) and a :ref:`Vector3` for the :ref:`origin` (last column). +A 3×4 matrix (3 rows, 4 columns) used for 3D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of a :ref:`basis` (first 3 columns) and a :ref:`Vector3` for the :ref:`origin` (last column). For more information, read the "Matrices and transforms" documentation article. diff --git a/classes/class_translation.rst b/classes/class_translation.rst index 88574cfee27..51ebb500bd8 100644 --- a/classes/class_translation.rst +++ b/classes/class_translation.rst @@ -14,14 +14,14 @@ Translation **Inherited By:** :ref:`OptimizedTranslation` -Language Translation. +A language translation that maps a collection of strings to their individual translations. .. rst-class:: classref-introduction-group Description ----------- -Translations are resources that can be loaded and unloaded on demand. They map a string to another string. +**Translation**\ s are resources that can be loaded and unloaded on demand. They map a collection of strings to their individual translations, and they also provide convenience methods for pluralization. .. rst-class:: classref-introduction-group diff --git a/classes/class_translationserver.rst b/classes/class_translationserver.rst index dda17a771d4..e8532a9c7b0 100644 --- a/classes/class_translationserver.rst +++ b/classes/class_translationserver.rst @@ -12,14 +12,14 @@ TranslationServer **Inherits:** :ref:`Object` -Server that manages all translations. +The server responsible for language translations. .. rst-class:: classref-introduction-group Description ----------- -Server that manages all translations. Translations can be set to it and removed from it. +The server that manages all language translations. Translations can be added to or removed from it. .. rst-class:: classref-introduction-group @@ -155,7 +155,7 @@ Clears the server from all translations. :ref:`int` **compare_locales** **(** :ref:`String` locale_a, :ref:`String` locale_b **)** |const| -Compares two locales and return similarity score between ``0``\ (no match) and ``10``\ (full match). +Compares two locales and returns a similarity score between ``0`` (no match) and ``10`` (full match). .. rst-class:: classref-item-separator @@ -167,7 +167,7 @@ Compares two locales and return similarity score between ``0``\ (no match) and ` :ref:`PackedStringArray` **get_all_countries** **(** **)** |const| -Returns array of known country codes. +Returns an array of known country codes. .. rst-class:: classref-item-separator @@ -191,7 +191,7 @@ Returns array of known language codes. :ref:`PackedStringArray` **get_all_scripts** **(** **)** |const| -Returns array of known script codes. +Returns an array of known script codes. .. rst-class:: classref-item-separator @@ -203,7 +203,7 @@ Returns array of known script codes. :ref:`String` **get_country_name** **(** :ref:`String` country **)** |const| -Returns readable country name for the ``country`` code. +Returns a readable country name for the ``country`` code. .. rst-class:: classref-item-separator @@ -215,7 +215,7 @@ Returns readable country name for the ``country`` code. :ref:`String` **get_language_name** **(** :ref:`String` language **)** |const| -Returns readable language name for the ``language`` code. +Returns a readable language name for the ``language`` code. .. rst-class:: classref-item-separator @@ -265,7 +265,7 @@ Returns a locale's language and its variant (e.g. ``"en_US"`` would return ``"En :ref:`String` **get_script_name** **(** :ref:`String` script **)** |const| -Returns readable script name for the ``script`` code. +Returns a readable script name for the ``script`` code. .. rst-class:: classref-item-separator @@ -355,7 +355,7 @@ If translations have been loaded beforehand for the new locale, they will be app :ref:`String` **standardize_locale** **(** :ref:`String` locale **)** |const| -Returns ``locale`` string standardized to match known locales (e.g. ``en-US`` would be matched to ``en_US``). +Returns a ``locale`` string standardized to match known locales (e.g. ``en-US`` would be matched to ``en_US``). .. rst-class:: classref-item-separator diff --git a/classes/class_tree.rst b/classes/class_tree.rst index f61310d9fc5..1f79ac935e7 100644 --- a/classes/class_tree.rst +++ b/classes/class_tree.rst @@ -12,16 +12,16 @@ Tree **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control to show a tree of items. +A control used to show a set of internal :ref:`TreeItem`\ s in a hierarchical structure. .. rst-class:: classref-introduction-group Description ----------- -This shows a tree of items that can be selected, expanded and collapsed. The tree can have multiple columns with custom controls like text editing, buttons and popups. It can be useful for structured displays and interactions. +A control used to show a set of internal :ref:`TreeItem`\ s in a hierarchical structure. The tree items can be selected, expanded and collapsed. The tree can have multiple columns with custom controls like :ref:`LineEdit`\ s, buttons and popups. It can be useful for structured displays and interactions. -Trees are built via code, using :ref:`TreeItem` objects to create the structure. They have a single root but multiple roots can be simulated if a dummy hidden root is added. +Trees are built via code, using :ref:`TreeItem` objects to create the structure. They have a single root, but multiple roots can be simulated with :ref:`hide_root`: .. tabs:: diff --git a/classes/class_treeitem.rst b/classes/class_treeitem.rst index 70ea745be9e..dcd799bb5ca 100644 --- a/classes/class_treeitem.rst +++ b/classes/class_treeitem.rst @@ -12,18 +12,18 @@ TreeItem **Inherits:** :ref:`Object` -Control for a single item inside a :ref:`Tree`. +An internal control for a single item inside :ref:`Tree`. .. rst-class:: classref-introduction-group Description ----------- -Control for a single item inside a :ref:`Tree`. May have child **TreeItem**\ s and be styled as well as contain buttons. +A single item of a :ref:`Tree` control. It can contain other **TreeItem**\ s as children, which allows it to create a hierarchy. It can also contain text and buttons. **TreeItem** is not a :ref:`Node`, it is internal to the :ref:`Tree`. -You can remove a **TreeItem** by using :ref:`Object.free`. +To create a **TreeItem**, use :ref:`Tree.create_item` or :ref:`create_child`. To remove a **TreeItem**, use :ref:`Object.free`. -\ **Note:** The ID values used for buttons are limited to 32 bits, not full 64 bits of :ref:`int`. This has a range of ``-2^32`` to ``2^32 - 1``, i.e. ``-2147483648`` to ``2147483647``. +\ **Note:** The ID values used for buttons are 32-bit, unlike :ref:`int` which is always 64-bit. They go from ``-2147483648`` to ``2147483647``. .. rst-class:: classref-reftable-group @@ -54,6 +54,8 @@ Methods +-------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_button` **(** :ref:`int` column, :ref:`Texture2D` button, :ref:`int` id=-1, :ref:`bool` disabled=false, :ref:`String` tooltip_text="" **)** | +-------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`add_child` **(** :ref:`TreeItem` child **)** | + +-------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`call_recursive` **(** :ref:`StringName` method, ... **)** |vararg| | +-------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear_custom_bg_color` **(** :ref:`int` column **)** | @@ -390,6 +392,18 @@ Adds a button with :ref:`Texture2D` ``button`` at column ``colu ---- +.. _class_TreeItem_method_add_child: + +.. rst-class:: classref-method + +void **add_child** **(** :ref:`TreeItem` child **)** + +Adds a previously unparented **TreeItem** as a direct child of this one. The ``child`` item must not be a part of any :ref:`Tree` or parented to any **TreeItem**. See also :ref:`remove_child`. + +.. rst-class:: classref-item-separator + +---- + .. _class_TreeItem_method_call_recursive: .. rst-class:: classref-method @@ -1104,7 +1118,9 @@ Propagates this item's checked status to its children and parents for the given void **remove_child** **(** :ref:`TreeItem` child **)** -Removes the given child **TreeItem** and all its children from the :ref:`Tree`. Note that it doesn't free the item from memory, so it can be reused later. To completely remove a **TreeItem** use :ref:`Object.free`. +Removes the given child **TreeItem** and all its children from the :ref:`Tree`. Note that it doesn't free the item from memory, so it can be reused later (see :ref:`add_child`). To completely remove a **TreeItem** use :ref:`Object.free`. + +\ **Note:** If you want to move a child from one :ref:`Tree` to another, then instead of removing and adding it manually you can use :ref:`move_before` or :ref:`move_after`. .. rst-class:: classref-item-separator diff --git a/classes/class_undoredo.rst b/classes/class_undoredo.rst index 36dd14b8e0d..183fb2c6d47 100644 --- a/classes/class_undoredo.rst +++ b/classes/class_undoredo.rst @@ -12,18 +12,18 @@ UndoRedo **Inherits:** :ref:`Object` -General-purpose helper to manage undo/redo operations. +Provides a high-level interface for implementing undo and redo operations. .. rst-class:: classref-introduction-group Description ----------- -UndoRedo works by registering methods and property changes inside "actions". +UndoRedo works by registering methods and property changes inside "actions". You can create an action, then provide ways to do and undo this action using function calls and property changes, then commit the action. -Common behavior is to create an action, then add do/undo calls to functions or property changes, then committing the action. +When an action is committed, all of the ``do_*`` methods will run. If the :ref:`undo` method is used, the ``undo_*`` methods will run. If the :ref:`redo` method is used, once again, all of the ``do_*`` methods will run. -Here's an example on how to add an UndoRedo action: +Here's an example on how to add an action: .. tabs:: @@ -81,7 +81,7 @@ Here's an example on how to add an UndoRedo action: \ :ref:`create_action`, :ref:`add_do_method`, :ref:`add_undo_method`, :ref:`add_do_property`, :ref:`add_undo_property`, and :ref:`commit_action` should be called one after the other, like in the example. Not doing so could lead to crashes. -If you don't need to register a method, you can leave :ref:`add_do_method` and :ref:`add_undo_method` out; the same goes for properties. You can also register more than one method/property. +If you don't need to register a method, you can leave :ref:`add_do_method` and :ref:`add_undo_method` out; the same goes for properties. You can also register more than one method/property in the order they should run. If you are making an :ref:`EditorPlugin` and want to integrate into the editor's undo history, use :ref:`EditorUndoRedoManager` instead. diff --git a/classes/class_variant.rst b/classes/class_variant.rst index c0ee3f24ec2..368331eb9c8 100644 --- a/classes/class_variant.rst +++ b/classes/class_variant.rst @@ -38,7 +38,7 @@ In computer programming, a Variant class is a class that is designed to store a var boo = "Boo is a string!"; var ref = new RefCounted(); // var is especially useful when used together with a constructor. - // Godot also provides a Variant type that works like an union of all the Variant-compatible types. + // Godot also provides a Variant type that works like a union of all the Variant-compatible types. Variant fooVar = 2; // fooVar is dynamically an integer (stored as a `long` in the Variant type). fooVar = "Now fooVar is a string!"; fooVar = new RefCounted(); // fooVar is a GodotObject. @@ -69,8 +69,7 @@ The global :ref:`@GlobalScope.typeof` function # To get the name of the underlying Object type, you need the `get_class()` method. print("foo is a(n) %s" % foo.get_class()) # inject the class name into a formatted string. # Note also that there is not yet any way to get a script's `class_name` string easily. - # To fetch that value, you can use [member ProjectSettings.get_global_class_list]. - # Open your project.godot file to see it up close. + # To fetch that value, you can use ProjectSettings.get_global_class_list(). .. code-tab:: csharp diff --git a/classes/class_vboxcontainer.rst b/classes/class_vboxcontainer.rst index 0a351ea10ca..5d10f047feb 100644 --- a/classes/class_vboxcontainer.rst +++ b/classes/class_vboxcontainer.rst @@ -14,21 +14,21 @@ VBoxContainer **Inherited By:** :ref:`ColorPicker`, :ref:`FileSystemDock`, :ref:`ScriptEditorBase` -Vertical box container. +A container that arranges its child controls vertically. .. rst-class:: classref-introduction-group Description ----------- -Vertical box container. See :ref:`BoxContainer`. +A variant of :ref:`BoxContainer` that can only arrange its child controls vertically. Child controls are rearranged automatically when their minimum size changes. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` - `3D Voxel Demo `__ diff --git a/classes/class_vector2.rst b/classes/class_vector2.rst index b501d9c4b35..efc95f6843c 100644 --- a/classes/class_vector2.rst +++ b/classes/class_vector2.rst @@ -10,14 +10,14 @@ Vector2 ======= -Vector used for 2D math using floating point coordinates. +A 2D vector using floating point coordinates. .. rst-class:: classref-introduction-group Description ----------- -2-element structure that can be used to represent positions in 2D space or any other pair of numeric values. +A 2-element structure that can be used to represent 2D coordinates or any other pair of numeric values. It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike :ref:`float` which is always 64-bit. If double precision is needed, compile the engine with the option ``precision=double``. @@ -939,6 +939,8 @@ Returns ``true`` if the vectors are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1075,6 +1077,8 @@ Divides each component of the **Vector2** by the given :ref:`int`. Compares two **Vector2** vectors by first checking if the X value of the left vector is less than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1087,6 +1091,8 @@ Compares two **Vector2** vectors by first checking if the X value of the left ve Compares two **Vector2** vectors by first checking if the X value of the left vector is less than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1101,6 +1107,8 @@ Returns ``true`` if the vectors are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1113,6 +1121,8 @@ Returns ``true`` if the vectors are exactly equal. Compares two **Vector2** vectors by first checking if the X value of the left vector is greater than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1125,6 +1135,8 @@ Compares two **Vector2** vectors by first checking if the X value of the left ve Compares two **Vector2** vectors by first checking if the X value of the left vector is greater than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vector2i.rst b/classes/class_vector2i.rst index 8808d0408a6..0016fa338bb 100644 --- a/classes/class_vector2i.rst +++ b/classes/class_vector2i.rst @@ -10,14 +10,14 @@ Vector2i ======== -Vector used for 2D math using integer coordinates. +A 2D vector using integer coordinates. .. rst-class:: classref-introduction-group Description ----------- -2-element structure that can be used to represent positions in 2D space or any other pair of numeric values. +A 2-element structure that can be used to represent 2D grid coordinates or any other pair of integers. It uses integer coordinates and is therefore preferable to :ref:`Vector2` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector2` this cannot be configured with an engine build option. Use :ref:`int` or :ref:`PackedInt64Array` if 64-bit values are needed. diff --git a/classes/class_vector3.rst b/classes/class_vector3.rst index 2f46417f0e7..dea2d5ef2eb 100644 --- a/classes/class_vector3.rst +++ b/classes/class_vector3.rst @@ -10,14 +10,14 @@ Vector3 ======= -Vector used for 3D math using floating point coordinates. +A 3D vector using floating point coordinates. .. rst-class:: classref-introduction-group Description ----------- -3-element structure that can be used to represent positions in 3D space or any other triplet of numeric values. +A 3-element structure that can be used to represent 3D coordinates or any other triplet of numeric values. It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike :ref:`float` which is always 64-bit. If double precision is needed, compile the engine with the option ``precision=double``. @@ -1011,6 +1011,8 @@ Returns ``true`` if the vectors are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1171,6 +1173,8 @@ Divides each component of the **Vector3** by the given :ref:`int`. Compares two **Vector3** vectors by first checking if the X value of the left vector is less than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1183,6 +1187,8 @@ Compares two **Vector3** vectors by first checking if the X value of the left ve Compares two **Vector3** vectors by first checking if the X value of the left vector is less than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1197,6 +1203,8 @@ Returns ``true`` if the vectors are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1209,6 +1217,8 @@ Returns ``true`` if the vectors are exactly equal. Compares two **Vector3** vectors by first checking if the X value of the left vector is greater than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -1221,6 +1231,8 @@ Compares two **Vector3** vectors by first checking if the X value of the left ve Compares two **Vector3** vectors by first checking if the X value of the left vector is greater than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, and then with the Z values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vector3i.rst b/classes/class_vector3i.rst index 8b346677ba1..d4c6a586442 100644 --- a/classes/class_vector3i.rst +++ b/classes/class_vector3i.rst @@ -10,14 +10,14 @@ Vector3i ======== -Vector used for 3D math using integer coordinates. +A 3D vector using integer coordinates. .. rst-class:: classref-introduction-group Description ----------- -3-element structure that can be used to represent positions in 3D space or any other triplet of numeric values. +A 3-element structure that can be used to represent 3D grid coordinates or any other triplet of integers. It uses integer coordinates and is therefore preferable to :ref:`Vector3` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector3` this cannot be configured with an engine build option. Use :ref:`int` or :ref:`PackedInt64Array` if 64-bit values are needed. diff --git a/classes/class_vector4.rst b/classes/class_vector4.rst index e3d2ba106c0..818cfdec675 100644 --- a/classes/class_vector4.rst +++ b/classes/class_vector4.rst @@ -10,14 +10,14 @@ Vector4 ======= -Vector used for 4D math using floating point coordinates. +A 4D vector using floating point coordinates. .. rst-class:: classref-introduction-group Description ----------- -4-element structure that can be used to represent any quadruplet of numeric values. +A 4-element structure that can be used to represent 4D coordinates or any other quadruplet of numeric values. It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike :ref:`float` which is always 64-bit. If double precision is needed, compile the engine with the option ``precision=double``. @@ -680,6 +680,8 @@ Returns ``true`` if the vectors are not equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -824,6 +826,8 @@ Divides each component of the **Vector4** by the given :ref:`int`. Compares two **Vector4** vectors by first checking if the X value of the left vector is less than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -836,6 +840,8 @@ Compares two **Vector4** vectors by first checking if the X value of the left ve Compares two **Vector4** vectors by first checking if the X value of the left vector is less than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -850,6 +856,8 @@ Returns ``true`` if the vectors are exactly equal. \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -862,6 +870,8 @@ Returns ``true`` if the vectors are exactly equal. Compares two **Vector4** vectors by first checking if the X value of the left vector is greater than the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- @@ -874,6 +884,8 @@ Compares two **Vector4** vectors by first checking if the X value of the left ve Compares two **Vector4** vectors by first checking if the X value of the left vector is greater than or equal to the X value of the ``right`` vector. If the X values are exactly equal, then it repeats this check with the Y values of the two vectors, Z values of the two vectors, and then with the W values. This operator is useful for sorting vectors. +\ **Note:** Vectors with :ref:`@GDScript.NAN` elements don't behave the same as other vectors. Therefore, the results from this operator may not be accurate if NaNs are included. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vector4i.rst b/classes/class_vector4i.rst index 0ee3718498c..7670f6a9e17 100644 --- a/classes/class_vector4i.rst +++ b/classes/class_vector4i.rst @@ -10,17 +10,19 @@ Vector4i ======== -Vector used for 4D math using integer coordinates. +A 4D vector using integer coordinates. .. rst-class:: classref-introduction-group Description ----------- -4-element structure that can be used to represent 4D grid coordinates or sets of integers. +A 4-element structure that can be used to represent 4D grid coordinates or any other quadruplet of integers. It uses integer coordinates and is therefore preferable to :ref:`Vector4` when exact precision is required. Note that the values are limited to 32 bits, and unlike :ref:`Vector4` this cannot be configured with an engine build option. Use :ref:`int` or :ref:`PackedInt64Array` if 64-bit values are needed. +\ **Note:** In a boolean context, a Vector4i will evaluate to ``false`` if it's equal to ``Vector4i(0, 0, 0, 0)``. Otherwise, a Vector3i will always evaluate to ``true``. + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_vehiclebody3d.rst b/classes/class_vehiclebody3d.rst index 54b51cad3c7..d99baf67d2b 100644 --- a/classes/class_vehiclebody3d.rst +++ b/classes/class_vehiclebody3d.rst @@ -12,20 +12,18 @@ VehicleBody3D **Inherits:** :ref:`RigidBody3D` **<** :ref:`PhysicsBody3D` **<** :ref:`CollisionObject3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Physics body that simulates the behavior of a car. +A 3D physics body that simulates the behavior of a car. .. rst-class:: classref-introduction-group Description ----------- -This node implements all the physics logic needed to simulate a car. It is based on the raycast vehicle system commonly found in physics engines. You will need to add a :ref:`CollisionShape3D` for the main body of your vehicle and add :ref:`VehicleWheel3D` nodes for the wheels. You should also add a :ref:`MeshInstance3D` to this node for the 3D model of your car but this model should not include meshes for the wheels. You should control the vehicle by using the :ref:`brake`, :ref:`engine_force`, and :ref:`steering` properties and not change the position or orientation of this node directly. +This physics body implements all the physics logic needed to simulate a car. It is based on the raycast vehicle system commonly found in physics engines. Aside from a :ref:`CollisionShape3D` for the main body of the vehicle, you must also add a :ref:`VehicleWheel3D` node for each wheel. You should also add a :ref:`MeshInstance3D` to this node for the 3D model of the vehicle, but this model should generally not include meshes for the wheels. You can control the vehicle by using the :ref:`brake`, :ref:`engine_force`, and :ref:`steering` properties. The position or orientation of this node shouldn't be changed directly. -\ **Note:** The origin point of your VehicleBody3D will determine the center of gravity of your vehicle so it is better to keep this low and move the :ref:`CollisionShape3D` and :ref:`MeshInstance3D` upwards. +\ **Note:** The origin point of your VehicleBody3D will determine the center of gravity of your vehicle. To make the vehicle more grounded, the origin point is usually kept low, moving the :ref:`CollisionShape3D` and :ref:`MeshInstance3D` upwards. -\ **Note:** This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you will probably have to write your own physics integration using another :ref:`PhysicsBody3D` class. - -\ **Warning:** With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead. +\ **Note:** This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you may have to write your own physics integration using :ref:`CharacterBody3D` or :ref:`RigidBody3D`. .. rst-class:: classref-introduction-group diff --git a/classes/class_vehiclewheel3d.rst b/classes/class_vehiclewheel3d.rst index 149963048b0..858571efb51 100644 --- a/classes/class_vehiclewheel3d.rst +++ b/classes/class_vehiclewheel3d.rst @@ -12,16 +12,16 @@ VehicleWheel3D **Inherits:** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` -Physics object that simulates the behavior of a wheel. +A 3D physics body for a :ref:`VehicleBody3D` that simulates the behavior of a wheel. .. rst-class:: classref-introduction-group Description ----------- -This node needs to be used as a child node of :ref:`VehicleBody3D` and simulates the behavior of one of its wheels. This node also acts as a collider to detect if the wheel is touching a surface. +A node used as a child of a :ref:`VehicleBody3D` parent to simulate the behavior of one of its wheels. This node also acts as a collider to detect if the wheel is touching a surface. -\ **Note:** This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you will probably have to write your own physics integration using another :ref:`PhysicsBody3D` class. +\ **Note:** This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you may need to write your own physics integration using another :ref:`PhysicsBody3D` class. .. rst-class:: classref-introduction-group diff --git a/classes/class_vflowcontainer.rst b/classes/class_vflowcontainer.rst index 1b785aae70a..341cdc46b88 100644 --- a/classes/class_vflowcontainer.rst +++ b/classes/class_vflowcontainer.rst @@ -12,14 +12,21 @@ VFlowContainer **Inherits:** :ref:`FlowContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical flow container. +A container that arranges its child controls vertically and wraps them around at the borders. .. rst-class:: classref-introduction-group Description ----------- -Vertical version of :ref:`FlowContainer`. +A variant of :ref:`FlowContainer` that can only arrange its child controls vertically, wrapping them around at the borders. This is similar to how text in a book wraps around when no more words can fit on a line, except vertically. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_videostreamplayer.rst b/classes/class_videostreamplayer.rst index 0070e1df9ab..fde17051c82 100644 --- a/classes/class_videostreamplayer.rst +++ b/classes/class_videostreamplayer.rst @@ -12,14 +12,14 @@ VideoStreamPlayer **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Control for playing video streams. +A control used for video playback. .. rst-class:: classref-introduction-group Description ----------- -Control node for playing video streams using :ref:`VideoStream` resources. +A control used for playback of :ref:`VideoStream` resources. Supported video formats are `Ogg Theora `__ (``.ogv``, :ref:`VideoStreamTheora`) and any format exposed via a GDExtension plugin. diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index c82b113608f..451cf9f4891 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -14,7 +14,7 @@ Viewport **Inherited By:** :ref:`SubViewport`, :ref:`Window` -Base class for viewports. +Abstract base class for viewports. Encapsulates drawing and interaction with a game world. .. rst-class:: classref-introduction-group @@ -23,7 +23,7 @@ Description A Viewport creates a different view into the screen, or a sub-view inside another viewport. Children 2D Nodes will display on it, and children Camera3D 3D nodes will render on it too. -Optionally, a viewport can have its own 2D or 3D world, so they don't share what they draw with other viewports. +Optionally, a viewport can have its own 2D or 3D world, so it doesn't share what it draws with other viewports. Viewports can also choose to be audio listeners, so they generate positional audio depending on a 2D or 3D camera child of it. @@ -207,6 +207,8 @@ Methods +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_positional_shadow_atlas_quadrant_subdiv` **(** :ref:`int` quadrant, :ref:`PositionalShadowAtlasQuadrantSubdiv` subdiv **)** | +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | void | :ref:`update_mouse_cursor_state` **(** **)** | + +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`warp_mouse` **(** :ref:`Vector2` position **)** | +-----------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -2066,6 +2068,10 @@ If an earlier method marks the input as handled via :ref:`set_input_as_handled` is ``true``, the event is used for physics object picking. +\ **Note:** This method doesn't propagate input events to embedded :ref:`Window`\ s or :ref:`SubViewport`\ s. + +\ **Note:** This method is deprecated, use :ref:`push_input` instead. + .. rst-class:: classref-item-separator ---- @@ -2108,6 +2114,18 @@ Sets the number of subdivisions to use in the specified quadrant. A higher numbe ---- +.. _class_Viewport_method_update_mouse_cursor_state: + +.. rst-class:: classref-method + +void **update_mouse_cursor_state** **(** **)** + +Force instantly updating the display based on the current mouse cursor position. This includes updating the mouse cursor shape and sending necessary :ref:`Control.mouse_entered`, :ref:`CollisionObject2D.mouse_entered`, :ref:`CollisionObject3D.mouse_entered` and :ref:`Window.mouse_entered` signals and their respective ``mouse_exited`` counterparts. + +.. rst-class:: classref-item-separator + +---- + .. _class_Viewport_method_warp_mouse: .. rst-class:: classref-method diff --git a/classes/class_viewporttexture.rst b/classes/class_viewporttexture.rst index cdacc5f0684..6b25e61219e 100644 --- a/classes/class_viewporttexture.rst +++ b/classes/class_viewporttexture.rst @@ -12,18 +12,18 @@ ViewportTexture **Inherits:** :ref:`Texture2D` **<** :ref:`Texture` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Texture which displays the content of a :ref:`Viewport`. +Provides the content of a :ref:`Viewport` as a dynamic texture. .. rst-class:: classref-introduction-group Description ----------- -Displays the content of a :ref:`Viewport` node as a dynamic :ref:`Texture2D`. This can be used to mix controls, 2D, and 3D elements in the same scene. +Provides the content of a :ref:`Viewport` as a dynamic :ref:`Texture2D`. This can be used to mix controls, 2D game objects, and 3D game objects in the same scene. -To create a ViewportTexture in code, use the :ref:`Viewport.get_texture` method on the target viewport. +To create a **ViewportTexture** in code, use the :ref:`Viewport.get_texture` method on the target viewport. -\ **Note:** When local to scene, this texture uses :ref:`Resource.setup_local_to_scene` to set the proxy texture and flags in the local viewport. Local to scene viewport textures will return incorrect data until the scene root is ready (see :ref:`Node.ready`). +\ **Note:** When local to scene, this texture uses :ref:`Resource.setup_local_to_scene` to set the proxy texture and flags in the local viewport. Local to scene **ViewportTexture**\ s will return incorrect data until the scene root is ready (see :ref:`Node.ready`). .. rst-class:: classref-introduction-group @@ -70,9 +70,9 @@ Property Descriptions - void **set_viewport_path_in_scene** **(** :ref:`NodePath` value **)** - :ref:`NodePath` **get_viewport_path_in_scene** **(** **)** -The path to the :ref:`Viewport` node to display. This is relative to the scene root, not to the node which uses the texture. +The path to the :ref:`Viewport` node to display. This is relative to the scene root, not to the node that uses the texture. -\ **Note:** In the editor, it is automatically updated when the target viewport's node path changes due to renaming or moving the viewport or its ancestors. At runtime, it may not be able to automatically update due to the inability to determine the scene root. +\ **Note:** In the editor, this path is automatically updated when the target viewport or one of its ancestors is renamed or moved. At runtime, the path may not be able to automatically update due to the inability to determine the scene root. .. |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_visualinstance3d.rst b/classes/class_visualinstance3d.rst index ef104aa9312..df8325d75d0 100644 --- a/classes/class_visualinstance3d.rst +++ b/classes/class_visualinstance3d.rst @@ -89,6 +89,10 @@ This object will only be visible for :ref:`Camera3D`\ s whose cu For :ref:`Light3D`\ s, this can be used to control which **VisualInstance3D**\ s are affected by a specific light. For :ref:`GPUParticles3D`, this can be used to control which particles are effected by a specific attractor. For :ref:`Decal`\ s, this can be used to control which **VisualInstance3D**\ s are affected by a specific decal. +To adjust :ref:`layers` more easily using a script, use :ref:`get_layer_mask_value` and :ref:`set_layer_mask_value`. + +\ **Note:** :ref:`VoxelGI`, SDFGI and :ref:`LightmapGI` will always take all layers into account to determine what contributes to global illumination. If this is an issue, set :ref:`GeometryInstance3D.gi_mode` to :ref:`GeometryInstance3D.GI_MODE_DISABLED` for meshes and :ref:`Light3D.light_bake_mode` to :ref:`Light3D.BAKE_DISABLED` for lights to exclude them from global illumination. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_vscrollbar.rst b/classes/class_vscrollbar.rst index 97ea17a34c6..2340e763844 100644 --- a/classes/class_vscrollbar.rst +++ b/classes/class_vscrollbar.rst @@ -12,14 +12,14 @@ VScrollBar **Inherits:** :ref:`ScrollBar` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical scroll bar. +A vertical scrollbar that goes from top (min) to bottom (max). .. rst-class:: classref-introduction-group Description ----------- -Vertical version of :ref:`ScrollBar`, which goes from top (min) to bottom (max). +A vertical scrollbar, typically used to navigate through content that extends beyond the visible height of a control. It is a :ref:`Range`-based control and goes from top (min) to bottom (max). Note that this direction is the opposite of :ref:`VSlider`'s. .. rst-class:: classref-reftable-group diff --git a/classes/class_vseparator.rst b/classes/class_vseparator.rst index 692f6f663db..a6be372cee9 100644 --- a/classes/class_vseparator.rst +++ b/classes/class_vseparator.rst @@ -12,14 +12,14 @@ VSeparator **Inherits:** :ref:`Separator` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical version of :ref:`Separator`. +A vertical line used for separating other controls. .. rst-class:: classref-introduction-group Description ----------- -Vertical version of :ref:`Separator`. Even though it looks vertical, it is used to separate objects horizontally. +A vertical separator used for separating other controls that are arranged **horizontally**. **VSeparator** is purely visual and normally drawn as a :ref:`StyleBoxLine`. .. rst-class:: classref-reftable-group diff --git a/classes/class_vslider.rst b/classes/class_vslider.rst index ed682e60acf..a5653748b2c 100644 --- a/classes/class_vslider.rst +++ b/classes/class_vslider.rst @@ -12,16 +12,14 @@ VSlider **Inherits:** :ref:`Slider` **<** :ref:`Range` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical slider. +A vertical slider that goes from bottom (min) to top (max). .. rst-class:: classref-introduction-group Description ----------- -Vertical slider. See :ref:`Slider`. This one goes from bottom (min) to top (max). - -\ **Note:** The :ref:`Range.changed` and :ref:`Range.value_changed` signals are part of the :ref:`Range` class which this class inherits from. +A vertical slider, used to adjust a value by moving a grabber along a vertical axis. It is a :ref:`Range`-based control and goes from bottom (min) to top (max). Note that this direction is the opposite of :ref:`VScrollBar`'s. .. rst-class:: classref-reftable-group diff --git a/classes/class_vsplitcontainer.rst b/classes/class_vsplitcontainer.rst index 489ec3927e5..ffd4a8390b2 100644 --- a/classes/class_vsplitcontainer.rst +++ b/classes/class_vsplitcontainer.rst @@ -12,21 +12,21 @@ VSplitContainer **Inherits:** :ref:`SplitContainer` **<** :ref:`Container` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -Vertical split container. +A container that splits two child controls vertically and provides a grabber for adjusting the split ratio. .. rst-class:: classref-introduction-group Description ----------- -Vertical split container. See :ref:`SplitContainer`. This goes from top to bottom. +A container that accepts only two child controls, then arranges them vertically and creates a divisor between them. The divisor can be dragged around to change the size relation between the child controls. .. rst-class:: classref-introduction-group Tutorials --------- -- :doc:`GUI containers <../tutorials/ui/gui_containers>` +- :doc:`Using Containers <../tutorials/ui/gui_containers>` .. rst-class:: classref-reftable-group diff --git a/classes/class_weakref.rst b/classes/class_weakref.rst index 517a77b7dfa..08bf9a5edc8 100644 --- a/classes/class_weakref.rst +++ b/classes/class_weakref.rst @@ -12,14 +12,14 @@ WeakRef **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -Holds an :ref:`Object`, but does not contribute to the reference count if the object is a reference. +Holds an :ref:`Object`. If the object is :ref:`RefCounted`, it doesn't update the reference count. .. rst-class:: classref-introduction-group Description ----------- -A weakref can hold a :ref:`RefCounted`, without contributing to the reference counter. A weakref can be created from an :ref:`Object` using :ref:`@GlobalScope.weakref`. If this object is not a reference, weakref still works, however, it does not have any effect on the object. Weakrefs are useful in cases where multiple classes have variables that refer to each other. Without weakrefs, using these classes could lead to memory leaks, since both references keep each other from being released. Making part of the variables a weakref can prevent this cyclic dependency, and allows the references to be released. +A weakref can hold a :ref:`RefCounted` without contributing to the reference counter. A weakref can be created from an :ref:`Object` using :ref:`@GlobalScope.weakref`. If this object is not a reference, weakref still works, however, it does not have any effect on the object. Weakrefs are useful in cases where multiple classes have variables that refer to each other. Without weakrefs, using these classes could lead to memory leaks, since both references keep each other from being released. Making part of the variables a weakref can prevent this cyclic dependency, and allows the references to be released. .. rst-class:: classref-reftable-group diff --git a/classes/class_window.rst b/classes/class_window.rst index 706a2e1c604..0ec909cd8c6 100644 --- a/classes/class_window.rst +++ b/classes/class_window.rst @@ -14,7 +14,7 @@ Window **Inherited By:** :ref:`AcceptDialog`, :ref:`Popup` -Base class for all windows. +Base class for all windows, dialogs, and popups. .. rst-class:: classref-introduction-group @@ -23,7 +23,7 @@ Description A node that creates a window. The window can either be a native system window or embedded inside another **Window** (see :ref:`Viewport.gui_embed_subwindows`). -At runtime, **Window**\ s will not close automatically when requested. You need to handle it manually using :ref:`close_requested` (this applies both to clicking close button and clicking outside popup). +At runtime, **Window**\ s will not close automatically when requested. You need to handle it manually using the :ref:`close_requested` signal (this applies both to pressing the close button and clicking outside of a popup). .. rst-class:: classref-reftable-group @@ -332,7 +332,7 @@ Emitted when the **Window**'s DPI changes as a result of OS-level changes (e.g. Emitted when files are dragged from the OS file manager and dropped in the game window. The argument is a list of file paths. -Note that this method only works with non-embedded windows, i.e. the main window and **Window**-derived nodes when :ref:`Viewport.gui_embed_subwindows` is disabled in the main viewport. +Note that this method only works with native windows, i.e. the main window and **Window**-derived nodes when :ref:`Viewport.gui_embed_subwindows` is disabled in the main viewport. Example usage: @@ -553,9 +553,9 @@ The window is floating on top of all other windows. This flag is ignored for ful :ref:`Flags` **FLAG_TRANSPARENT** = ``3`` -The window background can be transparent. +The window background can be transparent. Set with :ref:`transparent`. -\ **Note:** This flag has no effect if :ref:`ProjectSettings.display/window/per_pixel_transparency/allowed` is set to ``false``. Set with :ref:`transparent`. +\ **Note:** This flag has no effect if either :ref:`ProjectSettings.display/window/per_pixel_transparency/allowed`, or the window's :ref:`Viewport.transparent_bg` is set to ``false``. .. _class_Window_constant_FLAG_NO_FOCUS: @@ -573,6 +573,8 @@ The window can't be focused. No-focus window will ignore all input, except mouse Window is part of menu or :ref:`OptionButton` dropdown. This flag can't be changed when the window is visible. An active popup window will exclusively receive all input, without stealing focus from its parent. Popup windows are automatically closed when uses click outside it, or when an application is switched. Popup window must have transient parent set (see :ref:`transient`). +\ **Note:** This flag has no effect in embedded windows (unless said window is a :ref:`Popup`). + .. _class_Window_constant_FLAG_EXTEND_TO_TITLE: .. rst-class:: classref-enumeration-constant @@ -581,7 +583,9 @@ Window is part of menu or :ref:`OptionButton` dropdown. This Window content is expanded to the full size of the window. Unlike borderless window, the frame is left intact and can be used to resize the window, title bar is transparent, but have minimize/maximize/close buttons. Set with :ref:`extend_to_title`. -\ **Note:** This flag is implemented on macOS. +\ **Note:** This flag is implemented only on macOS. + +\ **Note:** This flag has no effect in embedded windows. .. _class_Window_constant_FLAG_MOUSE_PASSTHROUGH: @@ -591,6 +595,8 @@ Window content is expanded to the full size of the window. Unlike borderless win All mouse events are passed to the underlying window of the same application. +\ **Note:** This flag has no effect in embedded windows. + .. _class_Window_constant_FLAG_MAX: .. rst-class:: classref-enumeration-constant @@ -993,6 +999,10 @@ Needs :ref:`transient` enabled to work. If ``true``, the **Window** contents is expanded to the full size of the window, window title bar is transparent. +\ **Note:** This property is implemented only on macOS. + +\ **Note:** This property only works with native windows. + .. rst-class:: classref-item-separator ---- @@ -1008,9 +1018,7 @@ If ``true``, the **Window** contents is expanded to the full size of the window, - void **set_initial_position** **(** :ref:`WindowInitialPosition` value **)** - :ref:`WindowInitialPosition` **get_initial_position** **(** **)** -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Specifies the initial type of position for the **Window**. See :ref:`WindowInitialPosition` constants. .. rst-class:: classref-item-separator @@ -1069,6 +1077,8 @@ Set's the window's current mode. \ **Note:** Fullscreen mode is not exclusive full screen on Windows and Linux. +\ **Note:** This method only works with native windows, i.e. the main window and **Window**-derived nodes when :ref:`Viewport.gui_embed_subwindows` is disabled in the main viewport. + .. rst-class:: classref-item-separator ---- @@ -1088,6 +1098,8 @@ If ``true``, all mouse events will be passed to the underlying window of the sam \ **Note:** This property is implemented on Linux (X11), macOS and Windows. +\ **Note:** This property only works with native windows. + .. rst-class:: classref-item-separator ---- @@ -1157,6 +1169,8 @@ Passing an empty array will disable passthrough support (all mouse events will b If ``true``, the **Window** will be considered a popup. Popups are sub-windows that don't show as separate windows in system's window manager's window list and will send close request when anything is clicked outside of them (unless :ref:`exclusive` is enabled). +\ **Note:** This property only works with native windows. + .. rst-class:: classref-item-separator ---- @@ -1174,7 +1188,9 @@ If ``true``, the **Window** will be considered a popup. Popups are sub-windows t The window's position in pixels. -If :ref:`ProjectSettings.display/window/subwindows/embed_subwindows` is ``false``, the position is in absolute screen coordinates. This typically applies to editor plugins. If the setting is ``false``, the window's position is in the coordinates of its parent :ref:`Viewport`. +If :ref:`ProjectSettings.display/window/subwindows/embed_subwindows` is ``false``, the position is in absolute screen coordinates. This typically applies to editor plugins. If the setting is ``true``, the window's position is in the coordinates of its parent :ref:`Viewport`. + +\ **Note:** This property only works if :ref:`initial_position` is set to :ref:`WINDOW_INITIAL_POSITION_ABSOLUTE`. .. rst-class:: classref-item-separator @@ -1244,7 +1260,7 @@ The name of a theme type variation used by this **Window** to look up its own th - void **set_title** **(** :ref:`String` value **)** - :ref:`String` **get_title** **(** **)** -The window's title. If the **Window** is non-embedded, title styles set in :ref:`Theme` will have no effect. +The window's title. If the **Window** is native, title styles set in :ref:`Theme` will have no effect. .. rst-class:: classref-item-separator @@ -1282,10 +1298,10 @@ Note that behavior might be different depending on the platform. If ``true``, the **Window**'s background can be transparent. This is best used with embedded windows. -\ **Note:** For native windows, this flag has no effect if :ref:`ProjectSettings.display/window/per_pixel_transparency/allowed` is set to ``false``. - \ **Note:** Transparency support is implemented on Linux, macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. +\ **Note:** This property has no effect if either :ref:`ProjectSettings.display/window/per_pixel_transparency/allowed`, or the window's :ref:`Viewport.transparent_bg` is set to ``false``. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_world2d.rst b/classes/class_world2d.rst index 071d970bb9d..40c9377cd81 100644 --- a/classes/class_world2d.rst +++ b/classes/class_world2d.rst @@ -12,14 +12,14 @@ World2D **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Class that has everything pertaining to a 2D world. +A resource that holds all components of a 2D world, such as a canvas and a physics space. .. rst-class:: classref-introduction-group Description ----------- -Class that has everything pertaining to a 2D world. A physics space, a visual scenario and a sound space. 2D nodes register their resources into the current 2D world. +Class that has everything pertaining to a 2D world: A physics space, a canvas, and a sound space. 2D nodes register their resources into the current 2D world. .. rst-class:: classref-introduction-group diff --git a/classes/class_world3d.rst b/classes/class_world3d.rst index 78fb5151fab..236382b22d9 100644 --- a/classes/class_world3d.rst +++ b/classes/class_world3d.rst @@ -12,14 +12,14 @@ World3D **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -Class that has everything pertaining to a world. +A resource that holds all components of a 3D world, such as a visual scenario and a physics space. .. rst-class:: classref-introduction-group Description ----------- -Class that has everything pertaining to a world. A physics space, a visual scenario and a sound space. Node3D nodes register their resources into the current world. +Class that has everything pertaining to a world: A physics space, a visual scenario, and a sound space. 3D nodes register their resources into the current 3D world. .. rst-class:: classref-introduction-group diff --git a/classes/class_worldboundaryshape2d.rst b/classes/class_worldboundaryshape2d.rst index 6abcb039738..d9b9794ef3b 100644 --- a/classes/class_worldboundaryshape2d.rst +++ b/classes/class_worldboundaryshape2d.rst @@ -12,16 +12,14 @@ WorldBoundaryShape2D **Inherits:** :ref:`Shape2D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -World boundary (infinite plane) shape resource for 2D physics. +A 2D world boundary (half-plane) shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -2D world boundary shape to be added as a *direct* child of a :ref:`PhysicsBody2D` or :ref:`Area2D` using a :ref:`CollisionShape2D` node. **WorldBoundaryShape2D** works like an infinite plane and will not allow any physics body to go to the negative side. Note that the :ref:`normal` matters; anything "below" the plane will collide with it. If the **WorldBoundaryShape2D** is used in a :ref:`PhysicsBody2D`, it will cause colliding objects placed "below" it to teleport "above" the plane. - -\ **Performance:** Being a primitive collision shape, **WorldBoundaryShape2D** is fast to check collisions against. +A 2D world boundary shape, intended for use in physics. **WorldBoundaryShape2D** works like an infinite straight line that forces all physics bodies to stay above it. The line's normal determines which direction is considered as "above" and in the editor, the smaller line over it represents this direction. It can for example be used for endless flat floors. .. rst-class:: classref-reftable-group diff --git a/classes/class_worldboundaryshape3d.rst b/classes/class_worldboundaryshape3d.rst index 592abcdb6e4..56ff177fbd7 100644 --- a/classes/class_worldboundaryshape3d.rst +++ b/classes/class_worldboundaryshape3d.rst @@ -12,16 +12,14 @@ WorldBoundaryShape3D **Inherits:** :ref:`Shape3D` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -World boundary (infinite plane) shape resource for 3D physics. +A 3D world boundary (half-space) shape used for physics collision. .. rst-class:: classref-introduction-group Description ----------- -3D world boundary shape to be added as a *direct* child of a :ref:`PhysicsBody3D` or :ref:`Area3D` using a :ref:`CollisionShape3D` node. **WorldBoundaryShape3D** works like an infinite plane and will not allow any physics body to go to the negative side. Note that the :ref:`Plane`'s normal matters; anything "below" the plane will collide with it. If the **WorldBoundaryShape3D** is used in a :ref:`PhysicsBody3D`, it will cause colliding objects placed "below" it to teleport "above" the plane. - -\ **Performance:** Being a primitive collision shape, **WorldBoundaryShape3D** is fast to check collisions against. +A 3D world boundary shape, intended for use in physics. **WorldBoundaryShape3D** works like an infinite plane that forces all physics bodies to stay above it. The :ref:`plane`'s normal determines which direction is considered as "above" and in the editor, the line over the plane represents this direction. It can for example be used for endless flat floors. .. rst-class:: classref-reftable-group diff --git a/classes/class_xmlparser.rst b/classes/class_xmlparser.rst index 492c4196f3f..70d611c3e5e 100644 --- a/classes/class_xmlparser.rst +++ b/classes/class_xmlparser.rst @@ -12,6 +12,8 @@ XMLParser **Inherits:** :ref:`RefCounted` **<** :ref:`Object` +Provides a low-level interface for creating parsers for XML files. + Low-level class for creating parsers for `XML `__ files. .. rst-class:: classref-introduction-group @@ -19,7 +21,7 @@ Low-level class for creating parsers for `XML `__ files. This class can serve as base to make custom XML parsers. .. rst-class:: classref-reftable-group diff --git a/classes/class_zippacker.rst b/classes/class_zippacker.rst index 314fdbac849..7ad5e75b287 100644 --- a/classes/class_zippacker.rst +++ b/classes/class_zippacker.rst @@ -76,7 +76,7 @@ enum **ZipAppend**: :ref:`ZipAppend` **APPEND_CREATE** = ``0`` - +Create a new zip archive at the given path. .. _class_ZIPPacker_constant_APPEND_CREATEAFTER: @@ -84,7 +84,7 @@ enum **ZipAppend**: :ref:`ZipAppend` **APPEND_CREATEAFTER** = ``1`` - +Append a new zip archive to the end of the already existing file at the given path. .. _class_ZIPPacker_constant_APPEND_ADDINZIP: @@ -92,7 +92,7 @@ enum **ZipAppend**: :ref:`ZipAppend` **APPEND_ADDINZIP** = ``2`` - +Add new files to the existing zip archive at the given path. .. rst-class:: classref-section-separator diff --git a/classes/index.rst b/classes/index.rst index 8062af4dcd4..b09a656fec0 100644 --- a/classes/index.rst +++ b/classes/index.rst @@ -287,6 +287,7 @@ Resources class_animationnodestatemachine class_animationnodestatemachineplayback class_animationnodestatemachinetransition + class_animationnodesub2 class_animationnodesync class_animationnodetimescale class_animationnodetimeseek