From 795ca047a803048b7aa579f6c972583c8a7ad51b Mon Sep 17 00:00:00 2001 From: Godot Organization Date: Sat, 16 Aug 2025 03:52:50 +0000 Subject: [PATCH] classref: Sync with current master branch (0c51ede) --- classes/class_@gdscript.rst | 442 +- classes/class_@globalscope.rst | 855 ++- classes/class_aabb.rst | 183 +- classes/class_acceptdialog.rst | 91 +- classes/class_aescontext.rst | 29 +- classes/class_aimmodifier3d.rst | 197 + classes/class_animatablebody2d.rst | 14 +- classes/class_animatablebody3d.rst | 15 +- classes/class_animatedsprite2d.rst | 68 +- classes/class_animatedsprite3d.rst | 58 +- classes/class_animatedtexture.rst | 25 +- classes/class_animation.rst | 365 +- classes/class_animationlibrary.rst | 35 +- classes/class_animationmixer.rst | 246 +- classes/class_animationnode.rst | 113 +- classes/class_animationnodeadd2.rst | 1 + classes/class_animationnodeadd3.rst | 3 +- classes/class_animationnodeanimation.rst | 145 +- classes/class_animationnodeblend2.rst | 5 +- classes/class_animationnodeblend3.rst | 1 + classes/class_animationnodeblendspace1d.rst | 37 +- classes/class_animationnodeblendspace2d.rst | 59 +- classes/class_animationnodeblendtree.rst | 87 +- classes/class_animationnodeextension.rst | 95 + classes/class_animationnodeoneshot.rst | 66 +- classes/class_animationnodeoutput.rst | 5 +- classes/class_animationnodestatemachine.rst | 65 +- ...lass_animationnodestatemachineplayback.rst | 54 +- ...ss_animationnodestatemachinetransition.rst | 90 +- classes/class_animationnodesub2.rst | 1 + classes/class_animationnodesync.rst | 5 +- classes/class_animationnodetimescale.rst | 3 +- classes/class_animationnodetimeseek.rst | 39 +- classes/class_animationnodetransition.rst | 79 +- classes/class_animationplayer.rst | 449 +- classes/class_animationrootnode.rst | 1 + classes/class_animationtree.rst | 17 +- classes/class_area2d.rst | 81 +- classes/class_area3d.rst | 99 +- classes/class_array.rst | 849 +- classes/class_arraymesh.rst | 97 +- classes/class_arrayoccluder3d.rst | 15 +- classes/class_aspectratiocontainer.rst | 13 +- classes/class_astar2d.rst | 150 +- classes/class_astar3d.rst | 185 +- classes/class_astargrid2d.rst | 194 +- classes/class_atlastexture.rst | 13 +- classes/class_audiobuslayout.rst | 1 + classes/class_audioeffect.rst | 23 +- classes/class_audioeffectamplify.rst | 30 +- classes/class_audioeffectbandlimitfilter.rst | 1 + classes/class_audioeffectbandpassfilter.rst | 1 + classes/class_audioeffectcapture.rst | 21 +- classes/class_audioeffectchorus.rst | 79 +- classes/class_audioeffectcompressor.rst | 17 +- classes/class_audioeffectdelay.rst | 27 +- classes/class_audioeffectdistortion.rst | 13 +- classes/class_audioeffecteq.rst | 7 +- classes/class_audioeffecteq10.rst | 1 + classes/class_audioeffecteq21.rst | 1 + classes/class_audioeffecteq6.rst | 1 + classes/class_audioeffectfilter.rst | 39 +- classes/class_audioeffecthardlimiter.rst | 113 + classes/class_audioeffecthighpassfilter.rst | 1 + classes/class_audioeffecthighshelffilter.rst | 1 + classes/class_audioeffectinstance.rst | 21 +- classes/class_audioeffectlimiter.rst | 11 +- classes/class_audioeffectlowpassfilter.rst | 1 + classes/class_audioeffectlowshelffilter.rst | 1 + classes/class_audioeffectnotchfilter.rst | 1 + classes/class_audioeffectpanner.rst | 3 +- classes/class_audioeffectphaser.rst | 13 +- classes/class_audioeffectpitchshift.rst | 9 +- classes/class_audioeffectrecord.rst | 13 +- classes/class_audioeffectreverb.rst | 19 +- classes/class_audioeffectspectrumanalyzer.rst | 15 +- ...ss_audioeffectspectrumanalyzerinstance.rst | 31 +- classes/class_audioeffectstereoenhance.rst | 17 +- classes/class_audiolistener2d.rst | 9 +- classes/class_audiolistener3d.rst | 88 +- classes/class_audiosample.rst | 34 + classes/class_audiosampleplayback.rst | 34 + classes/class_audioserver.rst | 259 +- classes/class_audiostream.rst | 133 +- classes/class_audiostreamgenerator.rst | 105 +- .../class_audiostreamgeneratorplayback.rst | 19 +- classes/class_audiostreaminteractive.rst | 556 ++ classes/class_audiostreammicrophone.rst | 1 + classes/class_audiostreammp3.rst | 60 +- classes/class_audiostreamoggvorbis.rst | 54 +- classes/class_audiostreamplayback.rst | 213 +- .../class_audiostreamplaybackinteractive.rst | 100 + .../class_audiostreamplaybackoggvorbis.rst | 1 + classes/class_audiostreamplaybackplaylist.rst | 25 + .../class_audiostreamplaybackpolyphonic.rst | 51 +- .../class_audiostreamplaybackresampled.rst | 21 +- .../class_audiostreamplaybacksynchronized.rst | 27 + classes/class_audiostreamplayer.rst | 140 +- classes/class_audiostreamplayer2d.rst | 138 +- classes/class_audiostreamplayer3d.rst | 114 +- classes/class_audiostreamplaylist.rst | 190 + classes/class_audiostreampolyphonic.rst | 5 +- classes/class_audiostreamrandomizer.rst | 25 +- classes/class_audiostreamsynchronized.rst | 154 + classes/class_audiostreamwav.rst | 131 +- classes/class_backbuffercopy.rst | 16 +- classes/class_basebutton.rst | 53 +- classes/class_basematerial3d.rst | 847 +- classes/class_basis.rst | 299 +- classes/class_bitmap.rst | 31 +- classes/class_bone2d.rst | 25 +- classes/class_boneattachment3d.rst | 107 +- classes/class_boneconstraint3d.rst | 239 + classes/class_bonemap.rst | 13 +- classes/class_bool.rst | 17 +- classes/class_boxcontainer.rst | 11 +- classes/class_boxmesh.rst | 9 +- classes/class_boxoccluder3d.rst | 3 +- classes/class_boxshape3d.rst | 9 +- classes/class_button.rst | 276 +- classes/class_buttongroup.rst | 12 +- classes/class_callable.rst | 147 +- classes/class_callbacktweener.rst | 11 +- classes/class_camera2d.rst | 142 +- classes/class_camera3d.rst | 89 +- classes/class_cameraattributes.rst | 17 +- classes/class_cameraattributesphysical.rst | 21 +- classes/class_cameraattributespractical.rst | 19 +- classes/class_camerafeed.rst | 224 +- classes/class_cameraserver.rst | 96 +- classes/class_cameratexture.rst | 7 +- classes/class_canvasgroup.rst | 15 +- classes/class_canvasitem.rst | 659 +- classes/class_canvasitemmaterial.rst | 17 +- classes/class_canvaslayer.rst | 39 +- classes/class_canvasmodulate.rst | 10 +- classes/class_canvastexture.rst | 15 +- classes/class_capsulemesh.rst | 13 +- classes/class_capsuleshape2d.rst | 40 +- classes/class_capsuleshape3d.rst | 42 +- classes/class_centercontainer.rst | 3 +- classes/class_characterbody2d.rst | 149 +- classes/class_characterbody3d.rst | 155 +- classes/class_charfxtransform.rst | 55 +- classes/class_checkbox.rst | 85 +- classes/class_checkbutton.rst | 88 +- classes/class_circleshape2d.rst | 3 +- classes/class_classdb.rst | 296 +- classes/class_codeedit.rst | 448 +- classes/class_codehighlighter.rst | 43 +- classes/class_collisionobject2d.rst | 87 +- classes/class_collisionobject3d.rst | 169 +- classes/class_collisionpolygon2d.rst | 23 +- classes/class_collisionpolygon3d.rst | 71 +- classes/class_collisionshape2d.rst | 25 +- classes/class_collisionshape3d.rst | 67 +- classes/class_color.rst | 567 +- classes/class_colorpalette.rst | 68 + classes/class_colorpicker.rst | 310 +- classes/class_colorpickerbutton.rst | 54 +- classes/class_colorrect.rst | 5 +- classes/class_compositor.rst | 12 +- classes/class_compositoreffect.rst | 59 +- classes/class_compressedcubemap.rst | 1 + classes/class_compressedcubemaparray.rst | 1 + classes/class_compressedtexture2d.rst | 5 +- classes/class_compressedtexture2darray.rst | 1 + classes/class_compressedtexture3d.rst | 5 +- classes/class_compressedtexturelayered.rst | 5 +- classes/class_concavepolygonshape2d.rst | 5 +- classes/class_concavepolygonshape3d.rst | 9 +- classes/class_conetwistjoint3d.rst | 39 +- classes/class_configfile.rst | 59 +- classes/class_confirmationdialog.rst | 11 +- classes/class_container.rst | 19 +- classes/class_control.rst | 1151 ++- classes/class_converttransformmodifier3d.rst | 426 + classes/class_convexpolygonshape2d.rst | 11 +- classes/class_convexpolygonshape3d.rst | 9 +- classes/class_copytransformmodifier3d.rst | 594 ++ classes/class_cpuparticles2d.rst | 555 +- classes/class_cpuparticles3d.rst | 344 +- classes/class_crypto.rst | 134 +- classes/class_cryptokey.rst | 15 +- classes/class_csgbox3d.rst | 5 +- classes/class_csgcombiner3d.rst | 1 + classes/class_csgcylinder3d.rst | 13 +- classes/class_csgmesh3d.rst | 9 +- classes/class_csgpolygon3d.rst | 126 +- classes/class_csgprimitive3d.rst | 3 +- classes/class_csgshape3d.rst | 107 +- classes/class_csgsphere3d.rst | 11 +- classes/class_csgtorus3d.rst | 13 +- classes/class_csharpscript.rst | 5 +- classes/class_cubemap.rst | 35 +- classes/class_cubemaparray.rst | 21 +- classes/class_curve.rst | 135 +- classes/class_curve2d.rst | 53 +- classes/class_curve3d.rst | 96 +- classes/class_curvetexture.rst | 13 +- classes/class_curvexyztexture.rst | 17 +- classes/class_cylindermesh.rst | 15 +- classes/class_cylindershape3d.rst | 11 +- classes/class_dampedspringjoint2d.rst | 11 +- classes/class_decal.rst | 37 +- classes/class_dictionary.rst | 506 +- classes/class_diraccess.rst | 247 +- classes/class_directionallight2d.rst | 7 +- classes/class_directionallight3d.rst | 31 +- classes/class_displayserver.rst | 4525 ++++++++--- classes/class_dtlsserver.rst | 63 +- classes/class_editorcommandpalette.rst | 7 +- classes/class_editorcontextmenuplugin.rst | 242 + classes/class_editordebuggerplugin.rst | 137 +- classes/class_editordebuggersession.rst | 43 +- classes/class_editorexportplatform.rst | 486 +- classes/class_editorexportplatformandroid.rst | 603 +- ...lass_editorexportplatformappleembedded.rst | 43 + .../class_editorexportplatformextension.rst | 563 ++ classes/class_editorexportplatformios.rst | 3112 +++++++- .../class_editorexportplatformlinuxbsd.rst | 47 +- classes/class_editorexportplatformmacos.rst | 2666 ++++++- classes/class_editorexportplatformpc.rst | 17 + .../class_editorexportplatformvisionos.rst | 2713 +++++++ classes/class_editorexportplatformweb.rst | 89 +- classes/class_editorexportplatformwindows.rst | 102 +- classes/class_editorexportplugin.rst | 323 +- classes/class_editorexportpreset.rst | 578 ++ classes/class_editorfeatureprofile.rst | 43 +- classes/class_editorfiledialog.rst | 280 +- classes/class_editorfilesystem.rst | 49 +- classes/class_editorfilesystemdirectory.rst | 29 +- ...itorfilesystemimportformatsupportquery.rst | 23 +- classes/class_editorimportplugin.rst | 133 +- classes/class_editorinspector.rst | 71 +- classes/class_editorinspectorplugin.rst | 35 +- classes/class_editorinterface.rst | 475 +- classes/class_editornode3dgizmo.rst | 101 +- classes/class_editornode3dgizmoplugin.rst | 87 +- classes/class_editorpaths.rst | 25 +- classes/class_editorplugin.rst | 399 +- classes/class_editorproperty.rst | 290 +- .../class_editorresourceconversionplugin.rst | 17 +- classes/class_editorresourcepicker.rst | 27 +- classes/class_editorresourcepreview.rst | 19 +- .../class_editorresourcepreviewgenerator.rst | 27 +- classes/class_editorresourcetooltipplugin.rst | 15 +- classes/class_editorsceneformatimporter.rst | 91 +- .../class_editorsceneformatimporterblend.rst | 3 +- ...lass_editorsceneformatimporterfbx2gltf.rst | 3 +- .../class_editorsceneformatimportergltf.rst | 1 + .../class_editorsceneformatimporterufbx.rst | 1 + classes/class_editorscenepostimport.rst | 15 +- classes/class_editorscenepostimportplugin.rst | 45 +- classes/class_editorscript.rst | 29 +- classes/class_editorscriptpicker.rst | 3 +- classes/class_editorselection.rst | 37 +- classes/class_editorsettings.rst | 4908 ++++++++---- classes/class_editorspinslider.rst | 127 +- classes/class_editorsyntaxhighlighter.rst | 33 +- classes/class_editortoaster.rst | 102 + .../class_editortranslationparserplugin.rst | 78 +- classes/class_editorundoredomanager.rst | 131 +- classes/class_editorvcsinterface.rst | 201 +- classes/class_encodedobjectasid.rst | 7 +- classes/class_enetconnection.rst | 73 +- classes/class_enetmultiplayerpeer.rst | 23 +- classes/class_enetpacketpeer.rst | 75 +- classes/class_engine.rst | 273 +- classes/class_enginedebugger.rst | 249 +- classes/class_engineprofiler.rst | 9 +- classes/class_environment.rst | 265 +- classes/class_expression.rst | 25 +- classes/class_externaltexture.rst | 119 + classes/class_fastnoiselite.rst | 77 +- classes/class_fbxdocument.rst | 1 + classes/class_fbxstate.rst | 3 +- classes/class_fileaccess.rst | 611 +- classes/class_filedialog.rst | 752 +- classes/class_filesystemdock.rst | 37 +- classes/class_float.rst | 83 +- classes/class_flowcontainer.rst | 90 +- classes/class_fogmaterial.rst | 13 +- classes/class_fogvolume.rst | 7 +- classes/class_foldablecontainer.rst | 602 ++ classes/class_foldablegroup.rst | 131 + classes/class_font.rst | 237 +- classes/class_fontfile.rst | 264 +- classes/class_fontvariation.rst | 35 +- classes/class_framebuffercacherd.rst | 3 +- classes/class_gdextension.rst | 9 +- classes/class_gdextensionmanager.rst | 51 +- classes/class_gdscript.rst | 9 +- classes/class_gdscriptsyntaxhighlighter.rst | 49 + classes/class_generic6dofjoint3d.rst | 197 +- classes/class_geometry2d.rst | 138 +- classes/class_geometry3d.rst | 35 +- classes/class_geometryinstance3d.rst | 96 +- classes/class_gltfaccessor.rst | 349 +- classes/class_gltfanimation.rst | 13 +- classes/class_gltfbufferview.rst | 60 +- classes/class_gltfcamera.rst | 59 +- classes/class_gltfdocument.rst | 234 +- classes/class_gltfdocumentextension.rst | 249 +- ...tfdocumentextensionconvertimportermesh.rst | 1 + classes/class_gltflight.rst | 39 +- classes/class_gltfmesh.rst | 23 +- classes/class_gltfnode.rst | 124 +- classes/class_gltfobjectmodelproperty.rst | 378 + classes/class_gltfphysicsbody.rst | 43 +- classes/class_gltfphysicsshape.rst | 77 +- classes/class_gltfskeleton.rst | 27 +- classes/class_gltfskin.rst | 35 +- classes/class_gltfspecgloss.rst | 17 +- classes/class_gltfstate.rst | 374 +- classes/class_gltftexture.rst | 9 +- classes/class_gltftexturesampler.rst | 13 +- classes/class_gpuparticles2d.rst | 147 +- classes/class_gpuparticles3d.rst | 161 +- classes/class_gpuparticlesattractor3d.rst | 9 +- classes/class_gpuparticlesattractorbox3d.rst | 3 +- .../class_gpuparticlesattractorsphere3d.rst | 3 +- ...ass_gpuparticlesattractorvectorfield3d.rst | 5 +- classes/class_gpuparticlescollision3d.rst | 7 +- classes/class_gpuparticlescollisionbox3d.rst | 3 +- ...ass_gpuparticlescollisionheightfield3d.rst | 81 +- classes/class_gpuparticlescollisionsdf3d.rst | 17 +- .../class_gpuparticlescollisionsphere3d.rst | 3 +- classes/class_gradient.rst | 49 +- classes/class_gradienttexture1d.rst | 7 +- classes/class_gradienttexture2d.rst | 29 +- classes/class_graphedit.rst | 570 +- classes/class_graphelement.rst | 43 +- classes/class_graphframe.rst | 300 + classes/class_graphnode.rst | 191 +- classes/class_gridcontainer.rst | 9 +- classes/class_gridmap.rst | 101 +- classes/class_gridmapeditorplugin.rst | 166 + classes/class_groovejoint2d.rst | 5 +- classes/class_hashingcontext.rst | 29 +- classes/class_hboxcontainer.rst | 3 +- classes/class_heightmapshape3d.rst | 63 +- classes/class_hflowcontainer.rst | 1 + classes/class_hingejoint3d.rst | 83 +- classes/class_hmaccontext.rst | 18 +- classes/class_hscrollbar.rst | 1 + classes/class_hseparator.rst | 1 + classes/class_hslider.rst | 1 + classes/class_hsplitcontainer.rst | 1 + classes/class_httpclient.rst | 99 +- classes/class_httprequest.rst | 111 +- classes/class_image.rst | 307 +- classes/class_imageformatloader.rst | 3 +- classes/class_imageformatloaderextension.rst | 13 +- classes/class_imagetexture.rst | 29 +- classes/class_imagetexture3d.rst | 9 +- classes/class_imagetexturelayered.rst | 41 +- classes/class_immediatemesh.rst | 21 +- classes/class_importermesh.rst | 102 +- classes/class_importermeshinstance3d.rst | 21 +- classes/class_input.rst | 245 +- classes/class_inputevent.rst | 74 +- classes/class_inputeventaction.rst | 48 +- classes/class_inputeventfromwindow.rst | 3 +- classes/class_inputeventgesture.rst | 5 +- classes/class_inputeventjoypadbutton.rst | 7 +- classes/class_inputeventjoypadmotion.rst | 7 +- classes/class_inputeventkey.rst | 59 +- classes/class_inputeventmagnifygesture.rst | 3 +- classes/class_inputeventmidi.rst | 33 +- classes/class_inputeventmouse.rst | 15 +- classes/class_inputeventmousebutton.rst | 13 +- classes/class_inputeventmousemotion.rst | 37 +- classes/class_inputeventpangesture.rst | 3 +- classes/class_inputeventscreendrag.rst | 27 +- classes/class_inputeventscreentouch.rst | 13 +- classes/class_inputeventshortcut.rst | 7 +- classes/class_inputeventwithmodifiers.rst | 19 +- classes/class_inputmap.rst | 49 +- classes/class_instanceplaceholder.rst | 17 +- classes/class_int.rst | 87 +- classes/class_intervaltweener.rst | 5 +- classes/class_ip.rst | 33 +- classes/class_itemlist.rst | 587 +- classes/class_javaclass.rst | 71 +- classes/class_javaclasswrapper.rst | 68 +- classes/class_javaobject.rst | 65 + classes/class_javascriptbridge.rst | 55 +- classes/class_javascriptobject.rst | 21 +- classes/class_jnisingleton.rst | 1 + classes/class_joint2d.rst | 21 +- classes/class_joint3d.rst | 27 +- classes/class_json.rst | 95 +- classes/class_jsonrpc.rst | 53 +- classes/class_kinematiccollision2d.rst | 31 +- classes/class_kinematiccollision3d.rst | 33 +- classes/class_label.rst | 163 +- classes/class_label3d.rst | 116 +- classes/class_labelsettings.rst | 355 +- classes/class_light2d.rst | 43 +- classes/class_light3d.rst | 94 +- classes/class_lightmapgi.rst | 233 +- classes/class_lightmapgidata.rst | 85 +- classes/class_lightmapper.rst | 1 + classes/class_lightmapperrd.rst | 3 +- classes/class_lightmapprobe.rst | 5 +- classes/class_lightoccluder2d.rst | 7 +- classes/class_line2d.rst | 65 +- classes/class_lineedit.rst | 621 +- classes/class_linkbutton.rst | 49 +- classes/class_logger.rst | 132 + classes/class_lookatmodifier3d.rst | 720 ++ classes/class_mainloop.rst | 67 +- classes/class_margincontainer.rst | 9 +- classes/class_marker2d.rst | 3 +- classes/class_marker3d.rst | 3 +- classes/class_marshalls.rst | 17 +- classes/class_material.rst | 33 +- classes/class_menubar.rst | 117 +- classes/class_menubutton.rst | 18 +- classes/class_mesh.rst | 195 +- .../class_meshconvexdecompositionsettings.rst | 29 +- classes/class_meshdatatool.rst | 91 +- classes/class_meshinstance2d.rst | 7 +- classes/class_meshinstance3d.rst | 145 +- classes/class_meshlibrary.rst | 175 +- classes/class_meshtexture.rst | 7 +- classes/class_methodtweener.rst | 11 +- classes/class_missingnode.rst | 9 +- classes/class_missingresource.rst | 9 +- classes/class_mobilevrinterface.rst | 80 +- classes/class_modifierbonetarget3d.rst | 87 + classes/class_moviewriter.rst | 71 +- classes/class_multimesh.rst | 244 +- classes/class_multimeshinstance2d.rst | 7 +- classes/class_multimeshinstance3d.rst | 3 +- classes/class_multiplayerapi.rst | 57 +- classes/class_multiplayerapiextension.rst | 72 +- classes/class_multiplayerpeer.rst | 55 +- classes/class_multiplayerpeerextension.rst | 167 +- classes/class_multiplayerspawner.rst | 39 +- classes/class_multiplayersynchronizer.rst | 49 +- classes/class_mutex.rst | 11 +- classes/class_nativemenu.rst | 371 +- classes/class_navigationagent2d.rst | 255 +- classes/class_navigationagent3d.rst | 259 +- classes/class_navigationlink2d.rst | 65 +- classes/class_navigationlink3d.rst | 65 +- classes/class_navigationmesh.rst | 93 +- classes/class_navigationmeshgenerator.rst | 13 +- ...ass_navigationmeshsourcegeometrydata2d.rst | 169 +- ...ass_navigationmeshsourcegeometrydata3d.rst | 167 +- classes/class_navigationobstacle2d.rst | 99 +- classes/class_navigationobstacle3d.rst | 111 +- .../class_navigationpathqueryparameters2d.rst | 219 +- .../class_navigationpathqueryparameters3d.rst | 219 +- classes/class_navigationpathqueryresult2d.rst | 40 +- classes/class_navigationpathqueryresult3d.rst | 40 +- classes/class_navigationpolygon.rst | 178 +- classes/class_navigationregion2d.rst | 165 +- classes/class_navigationregion3d.rst | 55 +- classes/class_navigationserver2d.rst | 618 +- classes/class_navigationserver3d.rst | 549 +- classes/class_ninepatchrect.rst | 31 +- classes/class_node.rst | 1026 ++- classes/class_node2d.rst | 89 +- classes/class_node3d.rst | 358 +- classes/class_node3dgizmo.rst | 3 +- classes/class_nodepath.rst | 89 +- classes/class_noise.rst | 25 +- classes/class_noisetexture2d.rst | 27 +- classes/class_noisetexture3d.rst | 21 +- classes/class_object.rst | 692 +- classes/class_occluder3d.rst | 5 +- classes/class_occluderinstance3d.rst | 15 +- classes/class_occluderpolygon2d.rst | 11 +- classes/class_offlinemultiplayerpeer.rst | 5 +- classes/class_oggpacketsequence.rst | 11 +- classes/class_oggpacketsequenceplayback.rst | 1 + classes/class_omnilight3d.rst | 19 +- classes/class_openxraction.rst | 11 +- classes/class_openxractionbindingmodifier.rst | 34 + classes/class_openxractionmap.rst | 27 +- classes/class_openxractionset.rst | 13 +- .../class_openxranalogthresholdmodifier.rst | 125 + classes/class_openxrapiextension.rst | 495 +- classes/class_openxrbindingmodifier.rst | 79 + classes/class_openxrbindingmodifiereditor.rst | 104 + classes/class_openxrcompositionlayer.rst | 656 ++ .../class_openxrcompositionlayercylinder.rst | 125 + .../class_openxrcompositionlayerequirect.rst | 144 + ...t => class_openxrcompositionlayerquad.rst} | 35 +- classes/class_openxrdpadbindingmodifier.rst | 224 + classes/class_openxrextensionwrapper.rst | 679 ++ .../class_openxrextensionwrapperextension.rst | 408 +- classes/class_openxrfutureextension.rst | 101 + classes/class_openxrfutureresult.rst | 175 + classes/class_openxrhand.rst | 19 +- classes/class_openxrhapticbase.rst | 34 + classes/class_openxrhapticvibration.rst | 104 + classes/class_openxrinteractionprofile.rst | 66 +- .../class_openxrinteractionprofileeditor.rst | 32 + ...ass_openxrinteractionprofileeditorbase.rst | 77 + ...class_openxrinteractionprofilemetadata.rst | 13 +- classes/class_openxrinterface.rst | 499 +- classes/class_openxripbinding.rst | 125 +- classes/class_openxripbindingmodifier.rst | 34 + classes/class_openxrrendermodel.rst | 114 + classes/class_openxrrendermodelextension.rst | 278 + classes/class_openxrrendermodelmanager.rst | 163 + classes/class_openxrvisibilitymask.rst | 34 + classes/class_optimizedtranslation.rst | 5 +- classes/class_optionbutton.rst | 223 +- classes/class_ormmaterial3d.rst | 1 + classes/class_os.rst | 669 +- classes/class_packedbytearray.rst | 319 +- classes/class_packedcolorarray.rst | 101 +- classes/class_packeddatacontainer.rst | 22 +- classes/class_packeddatacontainerref.rst | 34 +- classes/class_packedfloat32array.rst | 103 +- classes/class_packedfloat64array.rst | 105 +- classes/class_packedint32array.rst | 101 +- classes/class_packedint64array.rst | 103 +- classes/class_packedscene.rst | 68 +- classes/class_packedstringarray.rst | 107 +- classes/class_packedvector2array.rst | 111 +- classes/class_packedvector3array.rst | 109 +- classes/class_packedvector4array.rst | 529 ++ classes/class_packetpeer.rst | 23 +- classes/class_packetpeerdtls.rst | 17 +- classes/class_packetpeerextension.rst | 13 +- classes/class_packetpeerstream.rst | 7 +- classes/class_packetpeerudp.rst | 80 +- classes/class_panel.rst | 9 +- classes/class_panelcontainer.rst | 7 +- classes/class_panoramaskymaterial.rst | 7 +- classes/class_parallax2d.rst | 76 +- classes/class_parallaxbackground.rst | 15 +- classes/class_parallaxlayer.rst | 25 +- classes/class_particleprocessmaterial.rst | 348 +- classes/class_path2d.rst | 3 +- classes/class_path3d.rst | 44 +- classes/class_pathfollow2d.rst | 17 +- classes/class_pathfollow3d.rst | 25 +- classes/class_pckpacker.rst | 39 +- classes/class_performance.rst | 273 +- classes/class_physicalbone2d.rst | 15 +- classes/class_physicalbone3d.rst | 131 +- classes/class_physicalbonesimulator3d.rst | 123 + classes/class_physicalskymaterial.rst | 25 +- classes/class_physicsbody2d.rst | 19 +- classes/class_physicsbody3d.rst | 35 +- classes/class_physicsdirectbodystate2d.rst | 137 +- ...lass_physicsdirectbodystate2dextension.rst | 487 +- classes/class_physicsdirectbodystate3d.rst | 141 +- ...lass_physicsdirectbodystate3dextension.rst | 343 +- classes/class_physicsdirectspacestate2d.rst | 27 +- ...ass_physicsdirectspacestate2dextension.rst | 45 +- classes/class_physicsdirectspacestate3d.rst | 23 +- ...ass_physicsdirectspacestate3dextension.rst | 51 +- classes/class_physicsmaterial.rst | 11 +- .../class_physicspointqueryparameters2d.rst | 23 +- .../class_physicspointqueryparameters3d.rst | 19 +- classes/class_physicsrayqueryparameters2d.rst | 25 +- classes/class_physicsrayqueryparameters3d.rst | 27 +- classes/class_physicsserver2d.rst | 427 +- classes/class_physicsserver2dextension.rst | 1403 ++-- classes/class_physicsserver2dmanager.rst | 5 +- classes/class_physicsserver3d.rst | 731 +- classes/class_physicsserver3dextension.rst | 1239 +-- classes/class_physicsserver3dmanager.rst | 5 +- ..._physicsserver3drenderingserverhandler.rst | 41 +- .../class_physicsshapequeryparameters2d.rst | 39 +- .../class_physicsshapequeryparameters3d.rst | 43 +- .../class_physicstestmotionparameters2d.rst | 23 +- .../class_physicstestmotionparameters3d.rst | 25 +- classes/class_physicstestmotionresult2d.rst | 33 +- classes/class_physicstestmotionresult3d.rst | 35 +- classes/class_pinjoint2d.rst | 13 +- classes/class_pinjoint3d.rst | 13 +- classes/class_placeholdercubemap.rst | 1 + classes/class_placeholdercubemaparray.rst | 1 + classes/class_placeholdermaterial.rst | 1 + classes/class_placeholdermesh.rst | 3 +- classes/class_placeholdertexture2d.rst | 3 +- classes/class_placeholdertexture2darray.rst | 1 + classes/class_placeholdertexture3d.rst | 3 +- classes/class_placeholdertexturelayered.rst | 5 +- classes/class_plane.rst | 61 +- classes/class_planemesh.rst | 15 +- classes/class_pointlight2d.rst | 9 +- classes/class_pointmesh.rst | 9 +- classes/class_polygon2d.rst | 67 +- classes/class_polygonoccluder3d.rst | 5 +- classes/class_polygonpathfinder.rst | 75 +- classes/class_popup.rst | 64 +- classes/class_popupmenu.rst | 700 +- classes/class_popuppanel.rst | 44 + classes/class_portablecompressedtexture2d.rst | 73 +- classes/class_primitivemesh.rst | 23 +- classes/class_prismmesh.rst | 11 +- classes/class_proceduralskymaterial.rst | 29 +- classes/class_progressbar.rst | 31 +- classes/class_projection.rst | 128 +- classes/class_projectsettings.rst | 6834 +++++++++++------ classes/class_propertytweener.rst | 96 +- classes/class_quadmesh.rst | 5 +- classes/class_quadoccluder3d.rst | 3 +- classes/class_quaternion.rst | 113 +- classes/class_randomnumbergenerator.rst | 29 +- classes/class_range.rst | 41 +- classes/class_raycast2d.rst | 94 +- classes/class_raycast3d.rst | 104 +- classes/class_rdattachmentformat.rst | 7 +- classes/class_rdframebufferpass.rst | 21 +- classes/class_rdpipelinecolorblendstate.rst | 11 +- ...ss_rdpipelinecolorblendstateattachment.rst | 25 +- classes/class_rdpipelinedepthstencilstate.rst | 51 +- classes/class_rdpipelinemultisamplestate.rst | 13 +- .../class_rdpipelinerasterizationstate.rst | 23 +- ...class_rdpipelinespecializationconstant.rst | 5 +- classes/class_rdsamplerstate.rst | 31 +- classes/class_rdshaderfile.rst | 9 +- classes/class_rdshadersource.rst | 19 +- classes/class_rdshaderspirv.rst | 43 +- classes/class_rdtextureformat.rst | 109 +- classes/class_rdtextureview.rst | 15 +- classes/class_rduniform.rst | 11 +- classes/class_rdvertexattribute.rst | 33 +- classes/class_rect2.rst | 105 +- classes/class_rect2i.rst | 73 +- classes/class_rectangleshape2d.rst | 7 +- classes/class_refcounted.rst | 15 +- classes/class_referencerect.rst | 11 +- classes/class_reflectionprobe.rst | 54 +- classes/class_regex.rst | 45 +- classes/class_regexmatch.rst | 19 +- classes/class_remotetransform2d.rst | 15 +- classes/class_remotetransform3d.rst | 15 +- classes/class_renderdata.rst | 11 +- classes/class_renderdataextension.rst | 19 +- classes/class_renderdatard.rst | 1 + classes/class_renderingdevice.rst | 1534 +++- classes/class_renderingserver.rst | 2614 +++++-- classes/class_renderscenebuffers.rst | 5 +- .../class_renderscenebuffersconfiguration.rst | 76 +- classes/class_renderscenebuffersextension.rst | 41 +- classes/class_renderscenebuffersrd.rst | 223 +- classes/class_renderscenedata.rst | 13 +- classes/class_renderscenedataextension.rst | 13 +- classes/class_renderscenedatard.rst | 1 + classes/class_resource.rst | 270 +- classes/class_resourceformatloader.rst | 51 +- classes/class_resourceformatsaver.rst | 15 +- classes/class_resourceimporter.rst | 45 +- classes/class_resourceimporterbitmap.rst | 5 +- classes/class_resourceimporterbmfont.rst | 7 +- .../class_resourceimportercsvtranslation.rst | 7 +- classes/class_resourceimporterdynamicfont.rst | 83 +- classes/class_resourceimporterimage.rst | 3 +- classes/class_resourceimporterimagefont.rst | 35 +- .../class_resourceimporterlayeredtexture.rst | 85 +- classes/class_resourceimportermp3.rst | 21 +- classes/class_resourceimporterobj.rst | 91 +- classes/class_resourceimporteroggvorbis.rst | 41 +- classes/class_resourceimporterscene.rst | 149 +- classes/class_resourceimportershaderfile.rst | 3 +- classes/class_resourceimportersvg.rst | 103 + classes/class_resourceimportertexture.rst | 233 +- .../class_resourceimportertextureatlas.rst | 9 +- classes/class_resourceimporterwav.rst | 49 +- classes/class_resourceloader.rst | 117 +- classes/class_resourcepreloader.rst | 15 +- classes/class_resourcesaver.rst | 47 +- classes/class_resourceuid.rst | 87 +- classes/class_retargetmodifier3d.rst | 262 + classes/class_ribbontrailmesh.rst | 17 +- classes/class_richtexteffect.rst | 5 +- classes/class_richtextlabel.rst | 1138 ++- classes/class_rid.rst | 23 +- classes/class_rigidbody2d.rst | 151 +- classes/class_rigidbody3d.rst | 147 +- classes/class_rootmotionview.rst | 11 +- classes/class_scenemultiplayer.rst | 51 +- classes/class_scenereplicationconfig.rst | 41 +- classes/class_scenestate.rst | 83 +- classes/class_scenetree.rst | 203 +- classes/class_scenetreetimer.rst | 9 +- classes/class_script.rst | 59 +- classes/class_scriptbacktrace.rst | 287 + classes/class_scriptcreatedialog.rst | 7 +- classes/class_scripteditor.rst | 106 +- classes/class_scripteditorbase.rst | 37 +- classes/class_scriptextension.rst | 245 +- classes/class_scriptlanguage.rst | 15 +- classes/class_scriptlanguageextension.rst | 415 +- classes/class_scrollbar.rst | 39 +- classes/class_scrollcontainer.rst | 78 +- classes/class_segmentshape2d.rst | 5 +- classes/class_semaphore.rst | 25 +- classes/class_separationrayshape2d.rst | 5 +- classes/class_separationrayshape3d.rst | 5 +- classes/class_separator.rst | 5 +- classes/class_shader.rst | 49 +- classes/class_shaderglobalsoverride.rst | 1 + classes/class_shaderinclude.rst | 3 +- classes/class_shaderincludedb.rst | 89 + classes/class_shadermaterial.rst | 9 +- classes/class_shape2d.rst | 15 +- classes/class_shape3d.rst | 7 +- classes/class_shapecast2d.rst | 89 +- classes/class_shapecast3d.rst | 93 +- classes/class_shortcut.rst | 71 +- classes/class_signal.rst | 205 +- classes/class_skeleton2d.rst | 19 +- classes/class_skeleton3d.rst | 527 +- classes/class_skeletonik3d.rst | 68 +- classes/class_skeletonmodification2d.rst | 31 +- classes/class_skeletonmodification2dccdik.rst | 37 +- .../class_skeletonmodification2dfabrik.rst | 23 +- .../class_skeletonmodification2djiggle.rst | 55 +- .../class_skeletonmodification2dlookat.rst | 27 +- ...ss_skeletonmodification2dphysicalbones.rst | 13 +- ...lass_skeletonmodification2dstackholder.rst | 5 +- .../class_skeletonmodification2dtwoboneik.rst | 27 +- classes/class_skeletonmodificationstack2d.rst | 25 +- classes/class_skeletonmodifier3d.rst | 275 + classes/class_skeletonprofile.rst | 81 +- classes/class_skeletonprofilehumanoid.rst | 5 +- classes/class_skin.rst | 23 +- classes/class_skinreference.rst | 30 +- classes/class_sky.rst | 15 +- classes/class_slider.rst | 141 +- classes/class_sliderjoint3d.rst | 103 +- classes/class_softbody3d.rst | 180 +- classes/class_spheremesh.rst | 11 +- classes/class_sphereoccluder3d.rst | 3 +- classes/class_sphereshape3d.rst | 5 +- classes/class_spinbox.rst | 469 +- classes/class_splitcontainer.rst | 361 +- classes/class_spotlight3d.rst | 21 +- classes/class_springarm3d.rst | 24 +- classes/class_springbonecollision3d.rst | 160 + .../class_springbonecollisioncapsule3d.rst | 127 + classes/class_springbonecollisionplane3d.rst | 32 + classes/class_springbonecollisionsphere3d.rst | 85 + classes/class_springbonesimulator3d.rst | 1401 ++++ classes/class_sprite2d.rst | 43 +- classes/class_sprite3d.rst | 19 +- classes/class_spritebase3d.rst | 73 +- classes/class_spriteframes.rst | 55 +- classes/class_standardmaterial3d.rst | 1 + classes/class_staticbody2d.rst | 16 +- classes/class_staticbody3d.rst | 17 +- classes/class_statusindicator.rst | 77 +- classes/class_streampeer.rst | 107 +- classes/class_streampeerbuffer.rst | 17 +- classes/class_streampeerextension.rst | 13 +- classes/class_streampeergzip.rst | 15 +- classes/class_streampeertcp.rst | 27 +- classes/class_streampeertls.rst | 25 +- classes/class_string.rst | 657 +- classes/class_stringname.rst | 627 +- classes/class_stylebox.rst | 97 +- classes/class_styleboxempty.rst | 1 + classes/class_styleboxflat.rst | 81 +- classes/class_styleboxline.rst | 11 +- classes/class_styleboxtexture.rst | 53 +- classes/class_subtweentweener.rst | 63 + classes/class_subviewport.rst | 29 +- classes/class_subviewportcontainer.rst | 30 +- classes/class_surfacetool.rst | 131 +- classes/class_svgtexture.rst | 191 + classes/class_syntaxhighlighter.rst | 31 +- classes/class_systemfont.rst | 90 +- classes/class_tabbar.rst | 230 +- classes/class_tabcontainer.rst | 231 +- classes/class_tcpserver.rst | 13 +- classes/class_textedit.rst | 1841 +++-- classes/class_textline.rst | 149 +- classes/class_textmesh.rst | 53 +- classes/class_textparagraph.rst | 284 +- classes/class_textserver.rst | 1830 +++-- classes/class_textserveradvanced.rst | 1 + classes/class_textserverdummy.rst | 1 + classes/class_textserverextension.rst | 2471 +++--- classes/class_textserverfallback.rst | 3 +- classes/class_textservermanager.rst | 21 +- classes/class_texture.rst | 1 + classes/class_texture2d.rst | 43 +- classes/class_texture2darray.rst | 5 +- classes/class_texture2darrayrd.rst | 1 + classes/class_texture2drd.rst | 3 +- classes/class_texture3d.rst | 83 +- classes/class_texture3drd.rst | 3 +- classes/class_texturebutton.rst | 37 +- classes/class_texturecubemaparrayrd.rst | 1 + classes/class_texturecubemaprd.rst | 1 + classes/class_texturelayered.rst | 93 +- classes/class_texturelayeredrd.rst | 3 +- classes/class_textureprogressbar.rst | 45 +- classes/class_texturerect.rst | 21 +- classes/class_theme.rst | 261 +- classes/class_themedb.rst | 17 +- classes/class_thread.rst | 33 +- classes/class_tiledata.rst | 301 +- classes/class_tilemap.rst | 250 +- classes/class_tilemaplayer.rst | 918 +++ classes/class_tilemappattern.rst | 25 +- classes/class_tileset.rst | 251 +- classes/class_tilesetatlassource.rst | 120 +- .../class_tilesetscenescollectionsource.rst | 64 +- classes/class_tilesetsource.rst | 17 +- classes/class_time.rst | 59 +- classes/class_timer.rst | 90 +- classes/class_tlsoptions.rst | 109 +- classes/class_torusmesh.rst | 9 +- classes/class_touchscreenbutton.rst | 31 +- classes/class_transform2d.rst | 263 +- classes/class_transform3d.rst | 129 +- classes/class_translation.rst | 33 +- classes/class_translationdomain.rst | 404 + classes/class_translationserver.rst | 123 +- classes/class_tree.rst | 456 +- classes/class_treeitem.rst | 819 +- classes/class_trianglemesh.rst | 108 +- classes/class_tubetrailmesh.rst | 19 +- classes/class_tween.rst | 250 +- classes/class_tweener.rst | 7 +- classes/class_udpserver.rst | 63 +- classes/class_undoredo.rst | 109 +- classes/class_uniformsetcacherd.rst | 3 +- classes/class_upnp.rst | 61 +- classes/class_upnpdevice.rst | 33 +- classes/class_variant.rst | 13 +- classes/class_vboxcontainer.rst | 3 +- classes/class_vector2.rst | 338 +- classes/class_vector2i.rst | 228 +- classes/class_vector3.rst | 362 +- classes/class_vector3i.rst | 238 +- classes/class_vector4.rst | 274 +- classes/class_vector4i.rst | 234 +- classes/class_vehiclebody3d.rst | 15 +- classes/class_vehiclewheel3d.rst | 151 +- classes/class_vflowcontainer.rst | 1 + classes/class_videostream.rst | 5 +- classes/class_videostreamplayback.rst | 45 +- classes/class_videostreamplayer.rst | 60 +- classes/class_videostreamtheora.rst | 3 +- classes/class_viewport.rst | 1031 ++- classes/class_viewporttexture.rst | 30 +- classes/class_visibleonscreenenabler2d.rst | 7 +- classes/class_visibleonscreenenabler3d.rst | 7 +- classes/class_visibleonscreennotifier2d.rst | 38 +- classes/class_visibleonscreennotifier3d.rst | 11 +- classes/class_visualinstance3d.rst | 29 +- classes/class_visualshader.rst | 87 +- classes/class_visualshadernode.rst | 46 +- classes/class_visualshadernodebillboard.rst | 9 +- .../class_visualshadernodebooleanconstant.rst | 3 +- ...class_visualshadernodebooleanparameter.rst | 5 +- classes/class_visualshadernodeclamp.rst | 5 +- .../class_visualshadernodecolorconstant.rst | 3 +- classes/class_visualshadernodecolorfunc.rst | 50 +- classes/class_visualshadernodecolorop.rst | 7 +- .../class_visualshadernodecolorparameter.rst | 5 +- classes/class_visualshadernodecomment.rst | 38 +- classes/class_visualshadernodecompare.rst | 21 +- classes/class_visualshadernodeconstant.rst | 1 + classes/class_visualshadernodecubemap.rst | 21 +- ...class_visualshadernodecubemapparameter.rst | 1 + .../class_visualshadernodecurvetexture.rst | 3 +- .../class_visualshadernodecurvexyztexture.rst | 3 +- classes/class_visualshadernodecustom.rst | 65 +- .../class_visualshadernodederivativefunc.rst | 19 +- classes/class_visualshadernodedeterminant.rst | 1 + .../class_visualshadernodedistancefade.rst | 1 + classes/class_visualshadernodedotproduct.rst | 1 + classes/class_visualshadernodeexpression.rst | 3 +- classes/class_visualshadernodefaceforward.rst | 1 + .../class_visualshadernodefloatconstant.rst | 3 +- classes/class_visualshadernodefloatfunc.rst | 7 +- classes/class_visualshadernodefloatop.rst | 7 +- .../class_visualshadernodefloatparameter.rst | 15 +- classes/class_visualshadernodeframe.rst | 193 + classes/class_visualshadernodefresnel.rst | 1 + ...class_visualshadernodeglobalexpression.rst | 1 + classes/class_visualshadernodegroupbase.rst | 59 +- classes/class_visualshadernodeif.rst | 1 + classes/class_visualshadernodeinput.rst | 7 +- classes/class_visualshadernodeintconstant.rst | 3 +- classes/class_visualshadernodeintfunc.rst | 7 +- classes/class_visualshadernodeintop.rst | 7 +- .../class_visualshadernodeintparameter.rst | 72 +- classes/class_visualshadernodeis.rst | 7 +- ...class_visualshadernodelinearscenedepth.rst | 1 + classes/class_visualshadernodemix.rst | 5 +- classes/class_visualshadernodemultiplyadd.rst | 5 +- .../class_visualshadernodeouterproduct.rst | 1 + classes/class_visualshadernodeoutput.rst | 1 + classes/class_visualshadernodeparameter.rst | 7 +- .../class_visualshadernodeparameterref.rst | 3 +- ...ss_visualshadernodeparticleaccelerator.rst | 5 +- ...ass_visualshadernodeparticleboxemitter.rst | 1 + ...s_visualshadernodeparticleconevelocity.rst | 1 + .../class_visualshadernodeparticleemit.rst | 5 +- .../class_visualshadernodeparticleemitter.rst | 3 +- ...ss_visualshadernodeparticlemeshemitter.rst | 7 +- ...lshadernodeparticlemultiplybyaxisangle.rst | 3 +- .../class_visualshadernodeparticleoutput.rst | 1 + ...ass_visualshadernodeparticlerandomness.rst | 5 +- ...ss_visualshadernodeparticleringemitter.rst | 1 + ..._visualshadernodeparticlesphereemitter.rst | 1 + .../class_visualshadernodeproximityfade.rst | 1 + classes/class_visualshadernoderandomrange.rst | 1 + classes/class_visualshadernoderemap.rst | 118 +- ....rst => class_visualshadernodereroute.rst} | 29 +- .../class_visualshadernoderesizablebase.rst | 5 +- .../class_visualshadernoderotationbyaxis.rst | 1 + classes/class_visualshadernodesample3d.rst | 5 +- ...visualshadernodescreennormalworldspace.rst | 1 + .../class_visualshadernodescreenuvtosdf.rst | 1 + classes/class_visualshadernodesdfraymarch.rst | 1 + .../class_visualshadernodesdftoscreenuv.rst | 1 + classes/class_visualshadernodesmoothstep.rst | 5 +- classes/class_visualshadernodestep.rst | 5 +- classes/class_visualshadernodeswitch.rst | 5 +- classes/class_visualshadernodetexture.rst | 15 +- .../class_visualshadernodetexture2darray.rst | 9 +- ...isualshadernodetexture2darrayparameter.rst | 1 + ...ass_visualshadernodetexture2dparameter.rst | 1 + classes/class_visualshadernodetexture3d.rst | 3 +- ...ass_visualshadernodetexture3dparameter.rst | 1 + ...class_visualshadernodetextureparameter.rst | 29 +- ...ualshadernodetextureparametertriplanar.rst | 1 + classes/class_visualshadernodetexturesdf.rst | 1 + ...class_visualshadernodetexturesdfnormal.rst | 1 + ...class_visualshadernodetransformcompose.rst | 1 + ...lass_visualshadernodetransformconstant.rst | 3 +- ...ass_visualshadernodetransformdecompose.rst | 1 + .../class_visualshadernodetransformfunc.rst | 7 +- classes/class_visualshadernodetransformop.rst | 7 +- ...ass_visualshadernodetransformparameter.rst | 5 +- ...class_visualshadernodetransformvecmult.rst | 7 +- .../class_visualshadernodeuintconstant.rst | 3 +- classes/class_visualshadernodeuintfunc.rst | 7 +- classes/class_visualshadernodeuintop.rst | 7 +- .../class_visualshadernodeuintparameter.rst | 5 +- classes/class_visualshadernodeuvfunc.rst | 7 +- .../class_visualshadernodeuvpolarcoord.rst | 1 + classes/class_visualshadernodevarying.rst | 5 +- .../class_visualshadernodevaryinggetter.rst | 1 + .../class_visualshadernodevaryingsetter.rst | 1 + .../class_visualshadernodevec2constant.rst | 3 +- .../class_visualshadernodevec2parameter.rst | 5 +- .../class_visualshadernodevec3constant.rst | 3 +- .../class_visualshadernodevec3parameter.rst | 5 +- .../class_visualshadernodevec4constant.rst | 3 +- .../class_visualshadernodevec4parameter.rst | 5 +- classes/class_visualshadernodevectorbase.rst | 5 +- .../class_visualshadernodevectorcompose.rst | 1 + .../class_visualshadernodevectordecompose.rst | 1 + .../class_visualshadernodevectordistance.rst | 1 + classes/class_visualshadernodevectorfunc.rst | 7 +- classes/class_visualshadernodevectorlen.rst | 1 + classes/class_visualshadernodevectorop.rst | 7 +- .../class_visualshadernodevectorrefract.rst | 1 + ...visualshadernodeworldpositionfromdepth.rst | 1 + classes/class_voxelgi.rst | 23 +- classes/class_voxelgidata.rst | 33 +- classes/class_vscrollbar.rst | 1 + classes/class_vseparator.rst | 1 + classes/class_vslider.rst | 1 + classes/class_vsplitcontainer.rst | 1 + classes/class_weakref.rst | 5 +- classes/class_webrtcdatachannel.rst | 33 +- classes/class_webrtcdatachannelextension.rst | 111 +- classes/class_webrtcmultiplayerpeer.rst | 29 +- classes/class_webrtcpeerconnection.rst | 63 +- .../class_webrtcpeerconnectionextension.rst | 69 +- classes/class_websocketmultiplayerpeer.rst | 33 +- classes/class_websocketpeer.rst | 106 +- classes/class_webxrinterface.rst | 139 +- classes/class_window.rst | 758 +- classes/class_workerthreadpool.rst | 63 +- classes/class_world2d.rst | 11 +- classes/class_world3d.rst | 17 +- classes/class_worldboundaryshape2d.rst | 5 +- classes/class_worldboundaryshape3d.rst | 5 +- classes/class_worldenvironment.rst | 13 +- classes/class_x509certificate.rst | 11 +- classes/class_xmlparser.rst | 41 +- classes/class_xranchor3d.rst | 7 +- classes/class_xrbodymodifier3d.rst | 69 +- classes/class_xrbodytracker.rst | 125 +- classes/class_xrcamera3d.rst | 15 +- classes/class_xrcontroller3d.rst | 37 +- classes/class_xrcontrollertracker.rst | 55 + classes/class_xrfacemodifier3d.rst | 17 +- classes/class_xrfacetracker.rst | 21 +- classes/class_xrhandmodifier3d.rst | 42 +- classes/class_xrhandtracker.rst | 112 +- classes/class_xrinterface.rst | 127 +- classes/class_xrinterfaceextension.rst | 235 +- classes/class_xrnode3d.rst | 58 +- classes/class_xrorigin3d.rst | 5 +- classes/class_xrpose.rst | 27 +- classes/class_xrpositionaltracker.rst | 126 +- classes/class_xrserver.rst | 454 +- classes/class_xrtracker.rst | 127 + classes/class_xrvrs.rst | 135 + classes/class_zippacker.rst | 104 +- classes/class_zipreader.rst | 90 +- classes/index.rst | 82 +- 1014 files changed, 92509 insertions(+), 36569 deletions(-) create mode 100644 classes/class_aimmodifier3d.rst create mode 100644 classes/class_animationnodeextension.rst create mode 100644 classes/class_audioeffecthardlimiter.rst create mode 100644 classes/class_audiosample.rst create mode 100644 classes/class_audiosampleplayback.rst create mode 100644 classes/class_audiostreaminteractive.rst create mode 100644 classes/class_audiostreamplaybackinteractive.rst create mode 100644 classes/class_audiostreamplaybackplaylist.rst create mode 100644 classes/class_audiostreamplaybacksynchronized.rst create mode 100644 classes/class_audiostreamplaylist.rst create mode 100644 classes/class_audiostreamsynchronized.rst create mode 100644 classes/class_boneconstraint3d.rst create mode 100644 classes/class_colorpalette.rst create mode 100644 classes/class_converttransformmodifier3d.rst create mode 100644 classes/class_copytransformmodifier3d.rst create mode 100644 classes/class_editorcontextmenuplugin.rst create mode 100644 classes/class_editorexportplatformappleembedded.rst create mode 100644 classes/class_editorexportplatformextension.rst create mode 100644 classes/class_editorexportplatformvisionos.rst create mode 100644 classes/class_editorexportpreset.rst create mode 100644 classes/class_editortoaster.rst create mode 100644 classes/class_externaltexture.rst create mode 100644 classes/class_foldablecontainer.rst create mode 100644 classes/class_foldablegroup.rst create mode 100644 classes/class_gdscriptsyntaxhighlighter.rst create mode 100644 classes/class_gltfobjectmodelproperty.rst create mode 100644 classes/class_graphframe.rst create mode 100644 classes/class_gridmapeditorplugin.rst create mode 100644 classes/class_javaobject.rst create mode 100644 classes/class_logger.rst create mode 100644 classes/class_lookatmodifier3d.rst create mode 100644 classes/class_modifierbonetarget3d.rst create mode 100644 classes/class_openxractionbindingmodifier.rst create mode 100644 classes/class_openxranalogthresholdmodifier.rst create mode 100644 classes/class_openxrbindingmodifier.rst create mode 100644 classes/class_openxrbindingmodifiereditor.rst create mode 100644 classes/class_openxrcompositionlayer.rst create mode 100644 classes/class_openxrcompositionlayercylinder.rst create mode 100644 classes/class_openxrcompositionlayerequirect.rst rename classes/{class_tilemaplayergroup.rst => class_openxrcompositionlayerquad.rst} (56%) create mode 100644 classes/class_openxrdpadbindingmodifier.rst create mode 100644 classes/class_openxrextensionwrapper.rst create mode 100644 classes/class_openxrfutureextension.rst create mode 100644 classes/class_openxrfutureresult.rst create mode 100644 classes/class_openxrhapticbase.rst create mode 100644 classes/class_openxrhapticvibration.rst create mode 100644 classes/class_openxrinteractionprofileeditor.rst create mode 100644 classes/class_openxrinteractionprofileeditorbase.rst create mode 100644 classes/class_openxripbindingmodifier.rst create mode 100644 classes/class_openxrrendermodel.rst create mode 100644 classes/class_openxrrendermodelextension.rst create mode 100644 classes/class_openxrrendermodelmanager.rst create mode 100644 classes/class_openxrvisibilitymask.rst create mode 100644 classes/class_packedvector4array.rst create mode 100644 classes/class_physicalbonesimulator3d.rst create mode 100644 classes/class_resourceimportersvg.rst create mode 100644 classes/class_retargetmodifier3d.rst create mode 100644 classes/class_scriptbacktrace.rst create mode 100644 classes/class_shaderincludedb.rst create mode 100644 classes/class_skeletonmodifier3d.rst create mode 100644 classes/class_springbonecollision3d.rst create mode 100644 classes/class_springbonecollisioncapsule3d.rst create mode 100644 classes/class_springbonecollisionplane3d.rst create mode 100644 classes/class_springbonecollisionsphere3d.rst create mode 100644 classes/class_springbonesimulator3d.rst create mode 100644 classes/class_subtweentweener.rst create mode 100644 classes/class_svgtexture.rst create mode 100644 classes/class_tilemaplayer.rst create mode 100644 classes/class_translationdomain.rst create mode 100644 classes/class_visualshadernodeframe.rst rename classes/{class_godotsharp.rst => class_visualshadernodereroute.rst} (53%) create mode 100644 classes/class_xrcontrollertracker.rst create mode 100644 classes/class_xrtracker.rst create mode 100644 classes/class_xrvrs.rst diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 041f71a42a5..9491dcf8f58 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -17,9 +17,9 @@ Built-in GDScript constants, functions, and annotations. Description ----------- -A list of GDScript-specific utility functions and annotations accessible from any script. +A list of utility functions and annotations accessible from any script written in GDScript. -For the list of the global functions and constants see :ref:`@GlobalScope`. +For the list of global functions and constants that can be accessed in any scripting language, see :ref:`@GlobalScope`. .. rst-class:: classref-introduction-group @@ -41,9 +41,9 @@ Methods +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`assert`\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`char`\ (\ char\: :ref:`int`\ ) | + | :ref:`String` | :ref:`char`\ (\ code\: :ref:`int`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`convert`\ (\ what\: :ref:`Variant`, type\: :ref:`int`\ ) | + | :ref:`Variant` | :ref:`convert`\ (\ what\: :ref:`Variant`, type\: :ref:`Variant.Type`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Object` | :ref:`dict_to_inst`\ (\ dictionary\: :ref:`Dictionary`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -57,6 +57,8 @@ Methods +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`load`\ (\ path\: :ref:`String`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`ord`\ (\ char\: :ref:`String`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`preload`\ (\ path\: :ref:`String`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`print_debug`\ (\ ...\ ) |vararg| | @@ -81,7 +83,7 @@ Constants .. rst-class:: classref-constant -**PI** = ``3.14159265358979`` +**PI** = ``3.14159265358979`` :ref:`🔗` Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to ``TAU / 2``, or 180 degrees in rotations. @@ -89,7 +91,7 @@ Constant that represents how many times the diameter of a circle fits around its .. rst-class:: classref-constant -**TAU** = ``6.28318530717959`` +**TAU** = ``6.28318530717959`` :ref:`🔗` The circle constant, the circumference of the unit circle in radians. This is equivalent to ``PI * 2``, or 360 degrees in rotations. @@ -97,7 +99,7 @@ The circle constant, the circumference of the unit circle in radians. This is eq .. rst-class:: classref-constant -**INF** = ``inf`` +**INF** = ``inf`` :ref:`🔗` Positive floating-point infinity. This is the result of floating-point division when the divisor is ``0.0``. For negative infinity, use ``-INF``. Dividing by ``-0.0`` will result in negative infinity if the numerator is positive, so dividing by ``0.0`` is not the same as dividing by ``-0.0`` (despite ``0.0 == -0.0`` returning ``true``). @@ -107,9 +109,11 @@ Positive floating-point infinity. This is the result of floating-point division .. rst-class:: classref-constant -**NAN** = ``nan`` +**NAN** = ``nan`` :ref:`🔗` + +"Not a Number", an invalid floating-point value. It is returned 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``. +\ :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``). Due to this, you must use :ref:`@GlobalScope.is_nan()` to check whether a number is equal to :ref:`NAN`. \ **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. @@ -120,45 +124,76 @@ Positive floating-point infinity. This is the result of floating-point division Annotations ----------- +.. _class_@GDScript_annotation_@abstract: + +.. rst-class:: classref-annotation + +**@abstract**\ (\ ) :ref:`🔗` + +Marks a class or a method as abstract. + +An abstract class is a class that cannot be instantiated directly. Instead, it is meant to be inherited by other classes. Attempting to instantiate an abstract class will result in an error. + +An abstract method is a method that has no implementation. Therefore, a newline or a semicolon is expected after the function header. This defines a contract that inheriting classes must conform to, because the method signature must be compatible when overriding. + +Inheriting classes must either provide implementations for all abstract methods, or the inheriting class must be marked as abstract. If a class has at least one abstract method (either its own or an unimplemented inherited one), then it must also be marked as abstract. However, the reverse is not true: an abstract class is allowed to have no abstract methods. + +:: + + @abstract class Shape: + @abstract func draw() + + class Circle extends Shape: + func draw(): + print("Drawing a circle.") + + class Square extends Shape: + func draw(): + print("Drawing a square.") + +.. rst-class:: classref-item-separator + +---- + .. _class_@GDScript_annotation_@export: .. rst-class:: classref-annotation -**@export**\ (\ ) +**@export**\ (\ ) :ref:`🔗` Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property, use the type hint notation. :: extends Node - + enum Direction {LEFT, RIGHT, UP, DOWN} - + # Built-in types. @export var string = "" @export var int_number = 5 @export var float_number: float = 5 - + # Enums. @export var type: Variant.Type @export var format: Image.Format @export var direction: Direction - + # Resources. @export var image: Image @export var custom_resource: CustomResource - + # Nodes. @export var node: Node @export var custom_node: CustomNode - + # Typed arrays. @export var int_array: Array[int] @export var direction_array: Array[Direction] @export var image_array: Array[Image] @export var node_array: Array[Node] -\ **Note:** Custom resources and nodes must be registered as global classes using ``class_name``. +\ **Note:** Custom resources and nodes should be registered as global classes using ``class_name``, since the Inspector currently only supports global classes. Otherwise, a less specific type will be exported instead. \ **Note:** Node export is only supported in :ref:`Node`-derived classes and has a number of other limitations. @@ -170,7 +205,7 @@ Mark the following property as exported (editable in the Inspector dock and save .. rst-class:: classref-annotation -**@export_category**\ (\ name\: :ref:`String`\ ) +**@export_category**\ (\ name\: :ref:`String`\ ) :ref:`🔗` Define a new category for the following exported properties. This helps to organize properties in the Inspector dock. @@ -192,7 +227,7 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_CATEGORY` Export a :ref:`Color`, :ref:`Array`\ \[:ref:`Color`\ \], or :ref:`PackedColorArray` property without allowing its transparency (:ref:`Color.a`) to be edited. @@ -211,14 +246,16 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA`, hint_string\: :ref:`String`, usage\: |bitfield|\[:ref:`PropertyUsageFlags`\] = 6\ ) +**@export_custom**\ (\ hint\: :ref:`PropertyHint`, hint_string\: :ref:`String`, usage\: |bitfield|\[:ref:`PropertyUsageFlags`\] = 6\ ) :ref:`🔗` -Allows you to set a custom hint, hint string, and usage flags for the exported property. Note that there's no validation done in GDScript, it will just pass the hint along to the editor. +Allows you to set a custom hint, hint string, and usage flags for the exported property. Note that there's no validation done in GDScript, it will just pass the parameters to the editor. :: @export_custom(PROPERTY_HINT_NONE, "suffix:m") var suffix: Vector3 +\ **Note:** Regardless of the ``usage`` value, the :ref:`@GlobalScope.PROPERTY_USAGE_SCRIPT_VARIABLE` flag is always added, as with any explicitly declared script variable. + .. rst-class:: classref-item-separator ---- @@ -227,7 +264,7 @@ Allows you to set a custom hint, hint string, and usage flags for the exported p .. rst-class:: classref-annotation -**@export_dir**\ (\ ) +**@export_dir**\ (\ ) :ref:`🔗` Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as a path to a directory. The path will be limited to the project folder and its subfolders. See :ref:`@export_global_dir` to allow picking from the entire filesystem. @@ -246,7 +283,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_DIR`, ...\ ) |vararg| +**@export_enum**\ (\ names\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` Export an :ref:`int`, :ref:`String`, :ref:`Array`\ \[:ref:`int`\ \], :ref:`Array`\ \[:ref:`String`\ \], :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, or :ref:`PackedStringArray` property as an enumerated list of options (or an array of options). If the property is an :ref:`int`, then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a :ref:`String`, then the value is stored. @@ -257,7 +294,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_ENUM` = "", ...\ ) |vararg| +**@export_exp_easing**\ (\ hints\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` Export a floating-point property with an easing editor widget. Additional hints can be provided to adjust the behavior of the widget. ``"attenuation"`` flips the curve, which makes it more intuitive for editing attenuation properties. ``"positive_only"`` limits values to only be greater than or equal to zero. @@ -306,7 +343,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_EXP_EASING` = "", ...\ ) |vararg| +**@export_file**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as a path to a file. The path will be limited to the project folder and its subfolders. See :ref:`@export_global_file` to allow picking from the entire filesystem. @@ -320,6 +357,20 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_FILE` methods to convert it to path. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GDScript_annotation_@export_file_path: + +.. rst-class:: classref-annotation + +**@export_file_path**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` + +Same as :ref:`@export_file`, except the file will be stored as a raw path. This means that it may become invalid when the file is moved. If you are exporting a :ref:`Resource` path, consider using :ref:`@export_file` instead. + .. rst-class:: classref-item-separator ---- @@ -328,7 +379,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_FILE`, ...\ ) |vararg| +**@export_flags**\ (\ names\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` Export an integer property as a bit flag field. This allows to store several "checked" or ``true`` values with one property, and comfortably select them from the Inspector dock. @@ -373,7 +424,7 @@ You can also use the annotation on :ref:`Array`\ \[:ref:`int` Export an integer property as a bit flag field for 2D navigation layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/2d_navigation/layer_1`. @@ -392,7 +443,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION` Export an integer property as a bit flag field for 2D physics layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/2d_physics/layer_1`. @@ -411,7 +462,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_PHYSICS` Export an integer property as a bit flag field for 2D render layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/2d_render/layer_1`. @@ -430,7 +481,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_RENDER` Export an integer property as a bit flag field for 3D navigation layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/3d_navigation/layer_1`. @@ -449,7 +500,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION` Export an integer property as a bit flag field for 3D physics layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/3d_physics/layer_1`. @@ -468,7 +519,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_PHYSICS` Export an integer property as a bit flag field for 3D render layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/3d_render/layer_1`. @@ -487,7 +538,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER` Export an integer property as a bit flag field for navigation avoidance layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/avoidance/layer_1`. @@ -506,7 +557,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE` Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as an absolute path to a directory. The path can be picked from the entire filesystem. See :ref:`@export_dir` to limit it to the project folder and its subfolders. @@ -525,7 +576,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_DIR` = "", ...\ ) |vararg| +**@export_global_file**\ (\ filter\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property as an absolute path to a file. The path can be picked from the entire filesystem. See :ref:`@export_file` to limit it to the project folder and its subfolders. @@ -547,7 +598,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE`, prefix\: :ref:`String` = ""\ ) +**@export_group**\ (\ name\: :ref:`String`, prefix\: :ref:`String` = ""\ ) :ref:`🔗` Define a new group for the following exported properties. This helps to organize properties in the Inspector dock. Groups can be added with an optional ``prefix``, which would make group to only consider properties that have this prefix. The grouping will break on the first property that doesn't have a prefix. The prefix is also removed from the property's name in the Inspector dock. @@ -562,11 +613,11 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_GROUP` Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], :ref:`PackedStringArray`, :ref:`Dictionary` or :ref:`Array`\ \[:ref:`Dictionary`\ \] property with a large :ref:`TextEdit` widget instead of a :ref:`LineEdit`. This adds support for multiline content and makes it easier to edit large amount of text stored in the property. @@ -597,7 +648,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_MULTILINE_TEXT` = "", ...\ ) |vararg| +**@export_node_path**\ (\ type\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` Export a :ref:`NodePath` or :ref:`Array`\ \[:ref:`NodePath`\ \] property with a filter for allowed node types. @@ -618,7 +669,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES`\ ) +**@export_placeholder**\ (\ placeholder\: :ref:`String`\ ) :ref:`🔗` Export a :ref:`String`, :ref:`Array`\ \[:ref:`String`\ \], or :ref:`PackedStringArray` property with a placeholder text displayed in the editor widget when no value is present. @@ -637,7 +688,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT`, max\: :ref:`float`, step\: :ref:`float` = 1.0, extra_hints\: :ref:`String` = "", ...\ ) |vararg| +**@export_range**\ (\ min\: :ref:`float`, max\: :ref:`float`, step\: :ref:`float` = 1.0, extra_hints\: :ref:`String` = "", ...\ ) |vararg| :ref:`🔗` Export an :ref:`int`, :ref:`float`, :ref:`Array`\ \[:ref:`int`\ \], :ref:`Array`\ \[:ref:`float`\ \], :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, :ref:`PackedFloat32Array`, or :ref:`PackedFloat64Array` property as a range value. The range must be defined by ``min`` and ``max``, as well as an optional ``step`` and a variety of extra hints. The ``step`` defaults to ``1`` for integer properties. For floating-point numbers this value depends on your :ref:`EditorSettings.interface/inspector/default_float_step` setting. @@ -653,10 +704,10 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_RANGE` -Export a property with :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag. The property is not displayed in the editor, but it is serialized and stored in the scene or resource file. This can be useful for :ref:`@tool` scripts. Also the property value is copied when :ref:`Resource.duplicate` or :ref:`Node.duplicate` is called, unlike non-exported variables. +Export a property with :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag. The property is not displayed in the editor, but it is serialized and stored in the scene or resource file. This can be useful for :ref:`@tool` scripts. Also the property value is copied when :ref:`Resource.duplicate()` or :ref:`Node.duplicate()` is called, unlike non-exported variables. :: @@ -687,7 +738,7 @@ Export a property with :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE`, prefix\: :ref:`String` = ""\ ) +**@export_subgroup**\ (\ name\: :ref:`String`, prefix\: :ref:`String` = ""\ ) :ref:`🔗` Define a new subgroup for the following exported properties. This helps to organize properties in the Inspector dock. Subgroups work exactly like groups, except they need a parent group to exist. See :ref:`@export_group`. @@ -698,12 +749,72 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_SUBGROUP`, icon\: :ref:`String` = ""\ ) :ref:`🔗` + +Export a :ref:`Callable` property as a clickable button with the label ``text``. When the button is pressed, the callable is called. + +If ``icon`` is specified, it is used to fetch an icon for the button via :ref:`Control.get_theme_icon()`, from the ``"EditorIcons"`` theme type. If ``icon`` is omitted, the default ``"Callable"`` icon is used instead. + +Consider using the :ref:`EditorUndoRedoManager` to allow the action to be reverted safely. + +See also :ref:`@GlobalScope.PROPERTY_HINT_TOOL_BUTTON`. + +:: + + @tool + extends Sprite2D + + @export_tool_button("Hello") var hello_action = hello + @export_tool_button("Randomize the color!", "ColorRect") + var randomize_color_action = randomize_color + + func hello(): + print("Hello world!") + + func randomize_color(): + var undo_redo = EditorInterface.get_editor_undo_redo() + undo_redo.create_action("Randomized Sprite2D Color") + undo_redo.add_do_property(self, &"self_modulate", Color(randf(), randf(), randf())) + undo_redo.add_undo_property(self, &"self_modulate", self_modulate) + undo_redo.commit_action() + +\ **Note:** The property is exported without the :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag because a :ref:`Callable` cannot be properly serialized and stored in a file. + +\ **Note:** In an exported project neither :ref:`EditorInterface` nor :ref:`EditorUndoRedoManager` exist, which may cause some scripts to break. To prevent this, you can use :ref:`Engine.get_singleton()` and omit the static type from the variable declaration: + +:: + + var undo_redo = Engine.get_singleton(&"EditorInterface").get_editor_undo_redo() + +\ **Note:** Avoid storing lambda callables in member variables of :ref:`RefCounted`-based classes (e.g. resources), as this can lead to memory leaks. Use only method callables and optionally :ref:`Callable.bind()` or :ref:`Callable.unbind()`. .. rst-class:: classref-item-separator @@ -713,7 +824,7 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_SUBGROUP`\ ) +**@icon**\ (\ icon_path\: :ref:`String`\ ) :ref:`🔗` Add a custom icon to the current script. The icon specified at ``icon_path`` is displayed in the Scene dock for every node of that class, as well as in various editor dialogs. @@ -725,7 +836,7 @@ Add a custom icon to the current script. The icon specified at ``icon_path`` is \ **Note:** As annotations describe their subject, the :ref:`@icon` annotation must be placed before the class definition and inheritance. -\ **Note:** Unlike other annotations, the argument of the :ref:`@icon` annotation must be a string literal (constant expressions are not supported). +\ **Note:** Unlike most other annotations, the argument of the :ref:`@icon` annotation must be a string literal (constant expressions are not supported). .. rst-class:: classref-item-separator @@ -735,13 +846,13 @@ Add a custom icon to the current script. The icon specified at ``icon_path`` is .. rst-class:: classref-annotation -**@onready**\ (\ ) +**@onready**\ (\ ) :ref:`🔗` -Mark the following property as assigned when the :ref:`Node` is ready. Values for these properties are not assigned immediately when the node is initialized (:ref:`Object._init`), and instead are computed and stored right before :ref:`Node._ready`. +Mark the following property as assigned when the :ref:`Node` is ready. Values for these properties are not assigned immediately when the node is initialized (:ref:`Object._init()`), and instead are computed and stored right before :ref:`Node._ready()`. :: - @onready var character_name: Label = $Label + @onready var character_name = $Label .. rst-class:: classref-item-separator @@ -751,13 +862,13 @@ Mark the following property as assigned when the :ref:`Node` is read .. rst-class:: classref-annotation -**@rpc**\ (\ mode\: :ref:`String` = "authority", sync\: :ref:`String` = "call_remote", transfer_mode\: :ref:`String` = "unreliable", transfer_channel\: :ref:`int` = 0\ ) +**@rpc**\ (\ mode\: :ref:`String` = "authority", sync\: :ref:`String` = "call_remote", transfer_mode\: :ref:`String` = "unreliable", transfer_channel\: :ref:`int` = 0\ ) :ref:`🔗` Mark the following method for remote procedure calls. See :doc:`High-level multiplayer <../tutorials/networking/high_level_multiplayer>`. -If ``mode`` is set as ``"any_peer"``, allows any peer to call this RPC function. Otherwise, only the authority peer is allowed to call it and ``mode`` should be kept as ``"authority"``. When configuring functions as RPCs with :ref:`Node.rpc_config`, each of these modes respectively corresponds to the :ref:`MultiplayerAPI.RPC_MODE_AUTHORITY` and :ref:`MultiplayerAPI.RPC_MODE_ANY_PEER` RPC modes. See :ref:`RPCMode`. If a peer that is not the authority tries to call a function that is only allowed for the authority, the function will not be executed. If the error can be detected locally (when the RPC configuration is consistent between the local and the remote peer), an error message will be displayed on the sender peer. Otherwise, the remote peer will detect the error and print an error there. +If ``mode`` is set as ``"any_peer"``, allows any peer to call this RPC function. Otherwise, only the authority peer is allowed to call it and ``mode`` should be kept as ``"authority"``. When configuring functions as RPCs with :ref:`Node.rpc_config()`, each of these modes respectively corresponds to the :ref:`MultiplayerAPI.RPC_MODE_AUTHORITY` and :ref:`MultiplayerAPI.RPC_MODE_ANY_PEER` RPC modes. See :ref:`RPCMode`. If a peer that is not the authority tries to call a function that is only allowed for the authority, the function will not be executed. If the error can be detected locally (when the RPC configuration is consistent between the local and the remote peer), an error message will be displayed on the sender peer. Otherwise, the remote peer will detect the error and print an error there. -If ``sync`` is set as ``"call_remote"``, the function will only be executed on the remote peer, but not locally. To run this function locally too, set ``sync`` to ``"call_local"``. When configuring functions as RPCs with :ref:`Node.rpc_config`, this is equivalent to setting ``call_local`` to ``true``. +If ``sync`` is set as ``"call_remote"``, the function will only be executed on the remote peer, but not locally. To run this function locally too, set ``sync`` to ``"call_local"``. When configuring functions as RPCs with :ref:`Node.rpc_config()`, this is equivalent to setting ``call_local`` to ``true``. The ``transfer_mode`` accepted values are ``"unreliable"``, ``"unreliable_ordered"``, or ``"reliable"``. It sets the transfer mode of the underlying :ref:`MultiplayerPeer`. See :ref:`MultiplayerPeer.transfer_mode`. @@ -769,13 +880,15 @@ The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter, but value @rpc func fn(): pass - + @rpc("any_peer", "unreliable_ordered") func fn_update_pos(): pass - + @rpc("authority", "call_remote", "unreliable", 0) # Equivalent to @rpc func fn_default(): pass +\ **Note:** Methods annotated with :ref:`@rpc` cannot receive objects which define required parameters in :ref:`Object._init()`. See :ref:`Object._init()` for more details. + .. rst-class:: classref-item-separator ---- @@ -784,10 +897,14 @@ The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter, but value .. rst-class:: classref-annotation -**@static_unload**\ (\ ) +**@static_unload**\ (\ ) :ref:`🔗` Make a script with static variables to not persist after all references are lost. If the script is loaded again the static variables will revert to their default values. +\ **Note:** As annotations describe their subject, the :ref:`@static_unload` annotation must be placed before the class definition and inheritance. + +\ **Warning:** Currently, due to a bug, scripts are never freed, even if :ref:`@static_unload` annotation is used. + .. rst-class:: classref-item-separator ---- @@ -796,7 +913,7 @@ Make a script with static variables to not persist after all references are lost .. rst-class:: classref-annotation -**@tool**\ (\ ) +**@tool**\ (\ ) :ref:`🔗` Mark the current script as a tool script, allowing it to be loaded and executed by the editor. See :doc:`Running code in the editor <../tutorials/plugins/running_code_in_the_editor>`. @@ -815,7 +932,7 @@ Mark the current script as a tool script, allowing it to be loaded and executed .. rst-class:: classref-annotation -**@warning_ignore**\ (\ warning\: :ref:`String`, ...\ ) |vararg| +**@warning_ignore**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` Mark the following statement to ignore the specified ``warning``. See :doc:`GDScript warning system <../tutorials/scripting/gdscript/warning_system>`. @@ -827,6 +944,48 @@ Mark the following statement to ignore the specified ``warning``. See :doc:`GDSc @warning_ignore("unreachable_code") print("unreachable") +See also :ref:`@warning_ignore_start` and :ref:`@warning_ignore_restore`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GDScript_annotation_@warning_ignore_restore: + +.. rst-class:: classref-annotation + +**@warning_ignore_restore**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` + +Stops ignoring the listed warning types after :ref:`@warning_ignore_start`. Ignoring the specified warning types will be reset to Project Settings. This annotation can be omitted to ignore the warning types until the end of the file. + +\ **Note:** Unlike most other annotations, arguments of the :ref:`@warning_ignore_restore` annotation must be string literals (constant expressions are not supported). + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GDScript_annotation_@warning_ignore_start: + +.. rst-class:: classref-annotation + +**@warning_ignore_start**\ (\ warning\: :ref:`String`, ...\ ) |vararg| :ref:`🔗` + +Starts ignoring the listed warning types until the end of the file or the :ref:`@warning_ignore_restore` annotation with the given warning type. + +:: + + func test(): + var a = 1 # Warning (if enabled in the Project Settings). + @warning_ignore_start("unused_variable") + var b = 2 # No warning. + var c = 3 # No warning. + @warning_ignore_restore("unused_variable") + var d = 4 # Warning (if enabled in the Project Settings). + +\ **Note:** To suppress a single warning, use :ref:`@warning_ignore` instead. + +\ **Note:** Unlike most other annotations, arguments of the :ref:`@warning_ignore_start` annotation must be string literals (constant expressions are not supported). + .. rst-class:: classref-section-separator ---- @@ -840,9 +999,11 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Color` **Color8**\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) +:ref:`Color` **Color8**\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) :ref:`🔗` -Returns a :ref:`Color` constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. Using :ref:`Color8` instead of the standard :ref:`Color` constructor is useful when you need to match exact color values in an :ref:`Image`. +**Deprecated:** Use :ref:`Color.from_rgba8()` instead. + +Returns a :ref:`Color` constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. Using :ref:`Color8()` instead of the standard :ref:`Color` constructor is useful when you need to match exact color values in an :ref:`Image`. :: @@ -850,7 +1011,7 @@ Returns a :ref:`Color` constructed from red (``r8``), green (``g8`` var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2). var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). -\ **Note:** Due to the lower precision of :ref:`Color8` compared to the standard :ref:`Color` constructor, a color created with :ref:`Color8` will generally not be equal to the same color created with the standard :ref:`Color` constructor. Use :ref:`Color.is_equal_approx` for comparisons to avoid issues with floating-point precision error. +\ **Note:** Due to the lower precision of :ref:`Color8()` compared to the standard :ref:`Color` constructor, a color created with :ref:`Color8()` will generally not be equal to the same color created with the standard :ref:`Color` constructor. Use :ref:`Color.is_equal_approx()` for comparisons to avoid issues with floating-point precision error. .. rst-class:: classref-item-separator @@ -860,13 +1021,13 @@ Returns a :ref:`Color` constructed from red (``r8``), green (``g8`` .. rst-class:: classref-method -|void| **assert**\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) +|void| **assert**\ (\ condition\: :ref:`bool`, message\: :ref:`String` = ""\ ) :ref:`🔗` -Asserts that the ``condition`` is ``true``. If the ``condition`` is ``false``, an error is generated. When running from the editor, the running project will also be paused until you resume it. This can be used as a stronger form of :ref:`@GlobalScope.push_error` for reporting errors to project developers or add-on users. +Asserts that the ``condition`` is ``true``. If the ``condition`` is ``false``, an error is generated. When running from the editor, the running project will also be paused until you resume it. This can be used as a stronger form of :ref:`@GlobalScope.push_error()` for reporting errors to project developers or add-on users. An optional ``message`` can be shown in addition to the generic "Assertion failed" message. You can use this to provide additional details about why the assertion failed. -\ **Warning:** For performance reasons, the code inside :ref:`assert` is only executed in debug builds or when running the project from the editor. Don't include code that has side effects in an :ref:`assert` call. Otherwise, the project will behave differently when exported in release mode. +\ **Warning:** For performance reasons, the code inside :ref:`assert()` is only executed in debug builds or when running the project from the editor. Don't include code that has side effects in an :ref:`assert()` call. Otherwise, the project will behave differently when exported in release mode. :: @@ -877,6 +1038,8 @@ An optional ``message`` can be shown in addition to the generic "Assertion faile assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check. assert(speed < 20, "the speed limit is 20") # Show a message. +\ **Note:** :ref:`assert()` is a keyword, not a function. So you cannot access it as a :ref:`Callable` or use it inside expressions. + .. rst-class:: classref-item-separator ---- @@ -885,15 +1048,16 @@ An optional ``message`` can be shown in addition to the generic "Assertion faile .. rst-class:: classref-method -:ref:`String` **char**\ (\ char\: :ref:`int`\ ) +:ref:`String` **char**\ (\ code\: :ref:`int`\ ) :ref:`🔗` -Returns a single character (as a :ref:`String`) of the given Unicode code point (which is compatible with ASCII code). +Returns a single character (as a :ref:`String` of length 1) of the given Unicode code point ``code``. :: - a = char(65) # a is "A" - a = char(65 + 32) # a is "a" - a = char(8364) # a is "€" + print(char(65)) # Prints "A" + print(char(129302)) # Prints "🤖" (robot face emoji) + +This is the inverse of :ref:`ord()`. See also :ref:`String.chr()` and :ref:`String.unicode_at()`. .. rst-class:: classref-item-separator @@ -903,9 +1067,9 @@ Returns a single character (as a :ref:`String`) of the given Unico .. rst-class:: classref-method -:ref:`Variant` **convert**\ (\ what\: :ref:`Variant`, type\: :ref:`int`\ ) +:ref:`Variant` **convert**\ (\ what\: :ref:`Variant`, type\: :ref:`Variant.Type`\ ) :ref:`🔗` -**Deprecated:** Use :ref:`@GlobalScope.type_convert` instead. +**Deprecated:** Use :ref:`@GlobalScope.type_convert()` instead. Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :ref:`Variant.Type` values. @@ -913,7 +1077,7 @@ Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :r var a = [4, 2.5, 1.2] print(a is Array) # Prints true - + var b = convert(a, TYPE_PACKED_BYTE_ARRAY) print(b) # Prints [4, 2, 1] print(b is Array) # Prints false @@ -926,9 +1090,11 @@ Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :r .. rst-class:: classref-method -:ref:`Object` **dict_to_inst**\ (\ dictionary\: :ref:`Dictionary`\ ) +:ref:`Object` **dict_to_inst**\ (\ dictionary\: :ref:`Dictionary`\ ) :ref:`🔗` -Converts a ``dictionary`` (created with :ref:`inst_to_dict`) back to an Object instance. Can be useful for deserializing. +**Deprecated:** Consider using :ref:`JSON.to_native()` or :ref:`Object.get_property_list()` instead. + +Converts a ``dictionary`` (created with :ref:`inst_to_dict()`) back to an Object instance. Can be useful for deserializing. .. rst-class:: classref-item-separator @@ -938,30 +1104,30 @@ Converts a ``dictionary`` (created with :ref:`inst_to_dict` **get_stack**\ (\ ) +:ref:`Array` **get_stack**\ (\ ) :ref:`🔗` -Returns an array of dictionaries representing the current call stack. See also :ref:`print_stack`. +Returns an array of dictionaries representing the current call stack. :: func _ready(): foo() - + func foo(): bar() - + func bar(): print(get_stack()) Starting from ``_ready()``, ``bar()`` would print: -.. code:: +.. code:: text [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}] -\ **Note:** This function only works if the running instance is connected to a debugging server (i.e. an editor instance). :ref:`get_stack` will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server. +See also :ref:`print_debug()`, :ref:`print_stack()`, and :ref:`Engine.capture_script_backtraces()`. -\ **Note:** Calling this function from a :ref:`Thread` is not supported. Doing so will return an empty array. +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks`. .. rst-class:: classref-item-separator @@ -971,11 +1137,11 @@ Starting from ``_ready()``, ``bar()`` would print: .. rst-class:: classref-method -:ref:`Dictionary` **inst_to_dict**\ (\ instance\: :ref:`Object`\ ) +:ref:`Dictionary` **inst_to_dict**\ (\ instance\: :ref:`Object`\ ) :ref:`🔗` -Returns the passed ``instance`` converted to a Dictionary. Can be useful for serializing. +**Deprecated:** Consider using :ref:`JSON.from_native()` or :ref:`Object.get_property_list()` instead. -\ **Note:** Cannot be used to serialize objects with built-in scripts attached or objects allocated within built-in scripts. +Returns the passed ``instance`` converted to a :ref:`Dictionary`. Can be useful for serializing. :: @@ -987,11 +1153,15 @@ Returns the passed ``instance`` converted to a Dictionary. Can be useful for ser Prints out: -.. code:: +.. code:: text [@subpath, @path, foo] [, res://test.gd, bar] +\ **Note:** This function can only be used to serialize objects with an attached :ref:`GDScript` stored in a separate file. Objects without an attached script, with a script written in another language, or with a built-in script are not supported. + +\ **Note:** This function is not recursive, which means that nested objects will not be represented as dictionaries. Also, properties passed by reference (:ref:`Object`, :ref:`Dictionary`, :ref:`Array`, and packed arrays) are copied by reference, not duplicated. + .. rst-class:: classref-item-separator ---- @@ -1000,7 +1170,7 @@ Prints out: .. rst-class:: classref-method -:ref:`bool` **is_instance_of**\ (\ value\: :ref:`Variant`, type\: :ref:`Variant`\ ) +:ref:`bool` **is_instance_of**\ (\ value\: :ref:`Variant`, type\: :ref:`Variant`\ ) :ref:`🔗` Returns ``true`` if ``value`` is an instance of ``type``. The ``type`` value must be one of the following: @@ -1010,9 +1180,9 @@ Returns ``true`` if ``value`` is an instance of ``type``. The ``type`` value mus - A :ref:`Script` (you can use any class, including inner one). -Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays) and is more performant. Use the operator instead of this method if you do not need dynamic type checking. +Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays). Use the operator instead of this method if you do not need to check the type dynamically. -Examples: +\ **Examples:**\ :: @@ -1021,9 +1191,9 @@ Examples: print(is_instance_of(a, MyClass)) print(is_instance_of(a, MyClass.InnerClass)) -\ **Note:** If ``value`` and/or ``type`` are freed objects (see :ref:`@GlobalScope.is_instance_valid`), or ``type`` is not one of the above options, this method will raise a runtime error. +\ **Note:** If ``value`` and/or ``type`` are freed objects (see :ref:`@GlobalScope.is_instance_valid()`), or ``type`` is not one of the above options, this method will raise a runtime error. -See also :ref:`@GlobalScope.typeof`, :ref:`type_exists`, :ref:`Array.is_same_typed` (and other :ref:`Array` methods). +See also :ref:`@GlobalScope.typeof()`, :ref:`type_exists()`, :ref:`Array.is_same_typed()` (and other :ref:`Array` methods). .. rst-class:: classref-item-separator @@ -1033,16 +1203,16 @@ See also :ref:`@GlobalScope.typeof`, :ref:`typ .. rst-class:: classref-method -:ref:`int` **len**\ (\ var\: :ref:`Variant`\ ) +:ref:`int` **len**\ (\ var\: :ref:`Variant`\ ) :ref:`🔗` Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String` or :ref:`StringName`, the element count of any array type, or the size of a :ref:`Dictionary`. For every other Variant type, a run-time error is generated and execution is stopped. :: - a = [1, 2, 3, 4] + var a = [1, 2, 3, 4] len(a) # Returns 4 - - b = "Hello!" + + var b = "Hello!" len(b) # Returns 6 .. rst-class:: classref-item-separator @@ -1053,9 +1223,9 @@ Returns the length of the given Variant ``var``. The length can be the character .. rst-class:: classref-method -:ref:`Resource` **load**\ (\ path\: :ref:`String`\ ) +:ref:`Resource` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -Returns a :ref:`Resource` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload`. This method is equivalent of using :ref:`ResourceLoader.load` with :ref:`ResourceLoader.CACHE_MODE_REUSE`. +Returns a :ref:`Resource` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload()`. This method is equivalent of using :ref:`ResourceLoader.load()` with :ref:`ResourceLoader.CACHE_MODE_REUSE`. \ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. @@ -1064,13 +1234,32 @@ Returns a :ref:`Resource` from the filesystem located at the abs # Load a scene called "main" located in the root of the project directory and cache it in a variable. var main = load("res://main.tscn") # main will contain a PackedScene resource. -\ **Important:** The path must be absolute. A relative path will always return ``null``. +\ **Important:** Relative paths are *not* relative to the script calling this method, instead it is prefixed with ``"res://"``. Loading from relative paths might not work as expected. -This function is a simplified version of :ref:`ResourceLoader.load`, which can be used for more advanced scenarios. +This function is a simplified version of :ref:`ResourceLoader.load()`, which can be used for more advanced scenarios. -\ **Note:** Files have to be imported into the engine first to load them using this function. If you want to load :ref:`Image`\ s at run-time, you may use :ref:`Image.load`. If you want to import audio files, you can use the snippet described in :ref:`AudioStreamMP3.data`. +\ **Note:** Files have to be imported into the engine first to load them using this function. If you want to load :ref:`Image`\ s at run-time, you may use :ref:`Image.load()`. If you want to import audio files, you can use the snippet described in :ref:`AudioStreamMP3.data`. -\ **Note:** If :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` is ``true``, :ref:`load` will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` to ``false``. +\ **Note:** If :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` is ``true``, :ref:`load()` will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` to ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_@GDScript_method_ord: + +.. rst-class:: classref-method + +:ref:`int` **ord**\ (\ char\: :ref:`String`\ ) :ref:`🔗` + +Returns an integer representing the Unicode code point of the given character ``char``, which should be a string of length 1. + +:: + + print(ord("A")) # Prints 65 + print(ord("🤖")) # Prints 129302 + +This is the inverse of :ref:`char()`. See also :ref:`String.chr()` and :ref:`String.unicode_at()`. .. rst-class:: classref-item-separator @@ -1080,9 +1269,9 @@ This function is a simplified version of :ref:`ResourceLoader.load` **preload**\ (\ path\: :ref:`String`\ ) +:ref:`Resource` **preload**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -Returns a :ref:`Resource` from the filesystem located at ``path``. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires ``path`` to be a constant :ref:`String`. If you want to load a resource from a dynamic/variable path, use :ref:`load`. +Returns a :ref:`Resource` from the filesystem located at ``path``. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires ``path`` to be a constant :ref:`String`. If you want to load a resource from a dynamic/variable path, use :ref:`load()`. \ **Note:** Resource paths can be obtained by right-clicking on a resource in the Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. @@ -1091,6 +1280,8 @@ Returns a :ref:`Resource` from the filesystem located at ``path` # Create instance of a scene. var diamond = preload("res://diamond.tscn").instantiate() +\ **Note:** :ref:`preload()` is a keyword, not a function. So you cannot access it as a :ref:`Callable`. + .. rst-class:: classref-item-separator ---- @@ -1099,18 +1290,20 @@ Returns a :ref:`Resource` from the filesystem located at ``path` .. rst-class:: classref-method -|void| **print_debug**\ (\ ...\ ) |vararg| +|void| **print_debug**\ (\ ...\ ) |vararg| :ref:`🔗` -Like :ref:`@GlobalScope.print`, but includes the current stack frame when running with the debugger turned on. +Like :ref:`@GlobalScope.print()`, but includes the current stack frame when running with the debugger turned on. The output in the console may look like the following: -.. code:: +.. code:: text Test print At: res://test.gd:15:_process() -\ **Note:** Calling this function from a :ref:`Thread` is not supported. Doing so will instead print the thread ID. +See also :ref:`print_stack()`, :ref:`get_stack()`, and :ref:`Engine.capture_script_backtraces()`. + +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks`. .. rst-class:: classref-item-separator @@ -1120,19 +1313,19 @@ The output in the console may look like the following: .. rst-class:: classref-method -|void| **print_stack**\ (\ ) +|void| **print_stack**\ (\ ) :ref:`🔗` -Prints a stack trace at the current code location. See also :ref:`get_stack`. +Prints a stack trace at the current code location. The output in the console may look like the following: -.. code:: +.. code:: text Frame 0 - res://test.gd:16 in function '_process' -\ **Note:** This function only works if the running instance is connected to a debugging server (i.e. an editor instance). :ref:`print_stack` will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server. +See also :ref:`print_debug()`, :ref:`get_stack()`, and :ref:`Engine.capture_script_backtraces()`. -\ **Note:** Calling this function from a :ref:`Thread` is not supported. Doing so will instead print the thread ID. +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks`. .. rst-class:: classref-item-separator @@ -1142,9 +1335,9 @@ The output in the console may look like the following: .. rst-class:: classref-method -:ref:`Array` **range**\ (\ ...\ ) |vararg| +:ref:`Array` **range**\ (\ ...\ ) |vararg| :ref:`🔗` -Returns an array with the given range. :ref:`range` can be called in three ways: +Returns an array with the given range. :ref:`range()` can be called in three ways: \ ``range(n: int)``: Starts from 0, increases by steps of 1, and stops *before* ``n``. The argument ``n`` is **exclusive**. @@ -1152,11 +1345,11 @@ Returns an array with the given range. :ref:`range \ ``range(b: int, n: int, s: int)``: Starts from ``b``, increases/decreases by steps of ``s``, and stops *before* ``n``. The arguments ``b`` and ``n`` are **inclusive** and **exclusive**, respectively. The argument ``s`` **can** be negative, but not ``0``. If ``s`` is ``0``, an error message is printed. -\ :ref:`range` converts all arguments to :ref:`int` before processing. +\ :ref:`range()` converts all arguments to :ref:`int` before processing. \ **Note:** Returns an empty array if no value meets the value constraint (e.g. ``range(2, 5, -1)`` or ``range(5, 5, 1)``). -Examples: +\ **Examples:**\ :: @@ -1175,7 +1368,7 @@ To iterate over an :ref:`Array` backwards, use: Output: -.. code:: +.. code:: text 9 6 @@ -1190,7 +1383,7 @@ To iterate over :ref:`float`, convert them in the loop. Output: -.. code:: +.. code:: text 0.3 0.2 @@ -1204,7 +1397,7 @@ Output: .. rst-class:: classref-method -:ref:`bool` **type_exists**\ (\ type\: :ref:`StringName`\ ) +:ref:`bool` **type_exists**\ (\ type\: :ref:`StringName`\ ) :ref:`🔗` Returns ``true`` if the given :ref:`Object`-derived class exists in :ref:`ClassDB`. Note that :ref:`Variant` data types are not registered in :ref:`ClassDB`. @@ -1214,6 +1407,7 @@ Returns ``true`` if the given :ref:`Object`-derived class exists i type_exists("NonExistentClass") # Returns false .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 4dded3653af..37b822d4e5c 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -21,7 +21,7 @@ A list of global scope enumerated constants and built-in functions. This is all Singletons are also documented here, since they can be accessed from anywhere. -For the entries related to GDScript which can be accessed in any script see :ref:`@GDScript`. +For the entries that can only be accessed from scripts written in GDScript, see :ref:`@GDScript`. .. note:: @@ -63,8 +63,6 @@ Properties +---------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`Geometry3D` | :ref:`Geometry3D` | +---------------------------------------------------------------+-------------------------------------------------------------------------------------+ - | :ref:`GodotSharp` | :ref:`GodotSharp` | - +---------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`IP` | :ref:`IP` | +---------------------------------------------------------------+-------------------------------------------------------------------------------------+ | :ref:`Input` | :ref:`Input` | @@ -371,7 +369,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **Side**: +enum **Side**: :ref:`🔗` .. _class_@GlobalScope_constant_SIDE_LEFT: @@ -413,7 +411,7 @@ Bottom side, usually used for :ref:`Control` or :ref:`StyleBox` .. _class_@GlobalScope_constant_CORNER_TOP_LEFT: @@ -455,7 +453,7 @@ Bottom-left corner. .. rst-class:: classref-enumeration -enum **Orientation**: +enum **Orientation**: :ref:`🔗` .. _class_@GlobalScope_constant_VERTICAL: @@ -481,7 +479,7 @@ General horizontal alignment, usually used for :ref:`Separator` .. rst-class:: classref-enumeration -enum **ClockDirection**: +enum **ClockDirection**: :ref:`🔗` .. _class_@GlobalScope_constant_CLOCKWISE: @@ -489,7 +487,7 @@ enum **ClockDirection**: :ref:`ClockDirection` **CLOCKWISE** = ``0`` -Clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90`). +Clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90()`). .. _class_@GlobalScope_constant_COUNTERCLOCKWISE: @@ -497,7 +495,7 @@ Clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90` **COUNTERCLOCKWISE** = ``1`` -Counter-clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90`). +Counter-clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90()`). .. rst-class:: classref-item-separator @@ -507,7 +505,7 @@ Counter-clockwise rotation. Used by some methods (e.g. :ref:`Image.rotate_90` .. _class_@GlobalScope_constant_HORIZONTAL_ALIGNMENT_LEFT: @@ -549,7 +547,7 @@ Expand row to fit width, usually for text-derived classes. .. rst-class:: classref-enumeration -enum **VerticalAlignment**: +enum **VerticalAlignment**: :ref:`🔗` .. _class_@GlobalScope_constant_VERTICAL_ALIGNMENT_TOP: @@ -591,7 +589,7 @@ Expand rows to fit height, usually for text-derived classes. .. rst-class:: classref-enumeration -enum **InlineAlignment**: +enum **InlineAlignment**: :ref:`🔗` .. _class_@GlobalScope_constant_INLINE_ALIGNMENT_TOP_TO: @@ -705,7 +703,7 @@ A bit mask for ``INLINE_ALIGNMENT_TO_*`` alignment constants. .. rst-class:: classref-enumeration -enum **EulerOrder**: +enum **EulerOrder**: :ref:`🔗` .. _class_@GlobalScope_constant_EULER_ORDER_XYZ: @@ -763,7 +761,7 @@ Specifies that Euler angles should be in ZYX order. When composing, the order is .. rst-class:: classref-enumeration -enum **Key**: +enum **Key**: :ref:`🔗` .. _class_@GlobalScope_constant_KEY_NONE: @@ -1427,7 +1425,7 @@ Help key. :ref:`Key` **KEY_BACK** = ``4194376`` -Media back key. Not to be confused with the Back button on an Android device. +Back key. .. _class_@GlobalScope_constant_KEY_FORWARD: @@ -1435,7 +1433,7 @@ Media back key. Not to be confused with the Back button on an Android device. :ref:`Key` **KEY_FORWARD** = ``4194377`` -Media forward key. +Forward key. .. _class_@GlobalScope_constant_KEY_STOP: @@ -1451,7 +1449,7 @@ Media stop key. :ref:`Key` **KEY_REFRESH** = ``4194379`` -Media refresh key. +Refresh key. .. _class_@GlobalScope_constant_KEY_VOLUMEDOWN: @@ -1755,7 +1753,7 @@ Space key. :ref:`Key` **KEY_EXCLAM** = ``33`` -! key. +Exclamation mark (``!``) key. .. _class_@GlobalScope_constant_KEY_QUOTEDBL: @@ -1763,7 +1761,7 @@ Space key. :ref:`Key` **KEY_QUOTEDBL** = ``34`` -" key. +Double quotation mark (``"``) key. .. _class_@GlobalScope_constant_KEY_NUMBERSIGN: @@ -1771,7 +1769,7 @@ Space key. :ref:`Key` **KEY_NUMBERSIGN** = ``35`` -# key. +Number sign or *hash* (``#``) key. .. _class_@GlobalScope_constant_KEY_DOLLAR: @@ -1779,7 +1777,7 @@ Space key. :ref:`Key` **KEY_DOLLAR** = ``36`` -$ key. +Dollar sign (``$``) key. .. _class_@GlobalScope_constant_KEY_PERCENT: @@ -1787,7 +1785,7 @@ $ key. :ref:`Key` **KEY_PERCENT** = ``37`` -% key. +Percent sign (``%``) key. .. _class_@GlobalScope_constant_KEY_AMPERSAND: @@ -1795,7 +1793,7 @@ $ key. :ref:`Key` **KEY_AMPERSAND** = ``38`` -& key. +Ampersand (``&``) key. .. _class_@GlobalScope_constant_KEY_APOSTROPHE: @@ -1803,7 +1801,7 @@ $ key. :ref:`Key` **KEY_APOSTROPHE** = ``39`` -' key. +Apostrophe (``'``) key. .. _class_@GlobalScope_constant_KEY_PARENLEFT: @@ -1811,7 +1809,7 @@ $ key. :ref:`Key` **KEY_PARENLEFT** = ``40`` -( key. +Left parenthesis (``(``) key. .. _class_@GlobalScope_constant_KEY_PARENRIGHT: @@ -1819,7 +1817,7 @@ $ key. :ref:`Key` **KEY_PARENRIGHT** = ``41`` -) key. +Right parenthesis (``)``) key. .. _class_@GlobalScope_constant_KEY_ASTERISK: @@ -1827,7 +1825,7 @@ $ key. :ref:`Key` **KEY_ASTERISK** = ``42`` -\* key. +Asterisk (``*``) key. .. _class_@GlobalScope_constant_KEY_PLUS: @@ -1835,7 +1833,7 @@ $ key. :ref:`Key` **KEY_PLUS** = ``43`` -+ key. +Plus (``+``) key. .. _class_@GlobalScope_constant_KEY_COMMA: @@ -1843,7 +1841,7 @@ $ key. :ref:`Key` **KEY_COMMA** = ``44`` -, key. +Comma (``,``) key. .. _class_@GlobalScope_constant_KEY_MINUS: @@ -1851,7 +1849,7 @@ $ key. :ref:`Key` **KEY_MINUS** = ``45`` -- key. +Minus (``-``) key. .. _class_@GlobalScope_constant_KEY_PERIOD: @@ -1859,7 +1857,7 @@ $ key. :ref:`Key` **KEY_PERIOD** = ``46`` -. key. +Period (``.``) key. .. _class_@GlobalScope_constant_KEY_SLASH: @@ -1867,7 +1865,7 @@ $ key. :ref:`Key` **KEY_SLASH** = ``47`` -/ key. +Slash (``/``) key. .. _class_@GlobalScope_constant_KEY_0: @@ -1955,7 +1953,7 @@ Number 9 key. :ref:`Key` **KEY_COLON** = ``58`` -: key. +Colon (``:``) key. .. _class_@GlobalScope_constant_KEY_SEMICOLON: @@ -1963,7 +1961,7 @@ Number 9 key. :ref:`Key` **KEY_SEMICOLON** = ``59`` -; key. +Semicolon (``;``) key. .. _class_@GlobalScope_constant_KEY_LESS: @@ -1971,7 +1969,7 @@ Number 9 key. :ref:`Key` **KEY_LESS** = ``60`` -< key. +Less-than sign (``<``) key. .. _class_@GlobalScope_constant_KEY_EQUAL: @@ -1979,7 +1977,7 @@ Number 9 key. :ref:`Key` **KEY_EQUAL** = ``61`` -= key. +Equal sign (``=``) key. .. _class_@GlobalScope_constant_KEY_GREATER: @@ -1987,7 +1985,7 @@ Number 9 key. :ref:`Key` **KEY_GREATER** = ``62`` -> key. +Greater-than sign (``>``) key. .. _class_@GlobalScope_constant_KEY_QUESTION: @@ -1995,7 +1993,7 @@ Number 9 key. :ref:`Key` **KEY_QUESTION** = ``63`` -? key. +Question mark (``?``) key. .. _class_@GlobalScope_constant_KEY_AT: @@ -2003,7 +2001,7 @@ Number 9 key. :ref:`Key` **KEY_AT** = ``64`` -@ key. +At sign (``@``) key. .. _class_@GlobalScope_constant_KEY_A: @@ -2219,7 +2217,7 @@ Z key. :ref:`Key` **KEY_BRACKETLEFT** = ``91`` -[ key. +Left bracket (``[lb]``) key. .. _class_@GlobalScope_constant_KEY_BACKSLASH: @@ -2227,7 +2225,7 @@ Z key. :ref:`Key` **KEY_BACKSLASH** = ``92`` -\\ key. +Backslash (``\``) key. .. _class_@GlobalScope_constant_KEY_BRACKETRIGHT: @@ -2235,7 +2233,7 @@ Z key. :ref:`Key` **KEY_BRACKETRIGHT** = ``93`` -] key. +Right bracket (``[rb]``) key. .. _class_@GlobalScope_constant_KEY_ASCIICIRCUM: @@ -2243,7 +2241,7 @@ Z key. :ref:`Key` **KEY_ASCIICIRCUM** = ``94`` -^ key. +Caret (``^``) key. .. _class_@GlobalScope_constant_KEY_UNDERSCORE: @@ -2251,7 +2249,7 @@ Z key. :ref:`Key` **KEY_UNDERSCORE** = ``95`` -\_ key. +Underscore (``_``) key. .. _class_@GlobalScope_constant_KEY_QUOTELEFT: @@ -2259,7 +2257,7 @@ Z key. :ref:`Key` **KEY_QUOTELEFT** = ``96`` -` key. +Backtick (`````) key. .. _class_@GlobalScope_constant_KEY_BRACELEFT: @@ -2267,7 +2265,7 @@ Z key. :ref:`Key` **KEY_BRACELEFT** = ``123`` -{ key. +Left brace (``{``) key. .. _class_@GlobalScope_constant_KEY_BAR: @@ -2275,7 +2273,7 @@ Z key. :ref:`Key` **KEY_BAR** = ``124`` -| key. +Vertical bar or *pipe* (``|``) key. .. _class_@GlobalScope_constant_KEY_BRACERIGHT: @@ -2283,7 +2281,7 @@ Z key. :ref:`Key` **KEY_BRACERIGHT** = ``125`` -} key. +Right brace (``}``) key. .. _class_@GlobalScope_constant_KEY_ASCIITILDE: @@ -2291,7 +2289,7 @@ Z key. :ref:`Key` **KEY_ASCIITILDE** = ``126`` -~ key. +Tilde (``~``) key. .. _class_@GlobalScope_constant_KEY_YEN: @@ -2299,7 +2297,7 @@ Z key. :ref:`Key` **KEY_YEN** = ``165`` -¥ key. +Yen symbol (``¥``) key. .. _class_@GlobalScope_constant_KEY_SECTION: @@ -2307,7 +2305,7 @@ Z key. :ref:`Key` **KEY_SECTION** = ``167`` -§ key. +Section sign (``§``) key. .. rst-class:: classref-item-separator @@ -2317,7 +2315,7 @@ Z key. .. rst-class:: classref-enumeration -flags **KeyModifierMask**: +flags **KeyModifierMask**: :ref:`🔗` .. _class_@GlobalScope_constant_KEY_CODE_MASK: @@ -2331,7 +2329,7 @@ Key Code mask. .. rst-class:: classref-enumeration-constant -:ref:`KeyModifierMask` **KEY_MODIFIER_MASK** = ``532676608`` +:ref:`KeyModifierMask` **KEY_MODIFIER_MASK** = ``2130706432`` Modifier key mask. @@ -2399,7 +2397,7 @@ Group Switch key mask. .. rst-class:: classref-enumeration -enum **KeyLocation**: +enum **KeyLocation**: :ref:`🔗` .. _class_@GlobalScope_constant_KEY_LOCATION_UNSPECIFIED: @@ -2409,7 +2407,7 @@ enum **KeyLocation**: Used for keys which only appear once, or when a comparison doesn't need to differentiate the ``LEFT`` and ``RIGHT`` versions. -For example, when using :ref:`InputEvent.is_match`, an event which has :ref:`KEY_LOCATION_UNSPECIFIED` will match any :ref:`KeyLocation` on the passed event. +For example, when using :ref:`InputEvent.is_match()`, an event which has :ref:`KEY_LOCATION_UNSPECIFIED` will match any :ref:`KeyLocation` on the passed event. .. _class_@GlobalScope_constant_KEY_LOCATION_LEFT: @@ -2435,7 +2433,7 @@ A key which is to the right of its twin. .. rst-class:: classref-enumeration -enum **MouseButton**: +enum **MouseButton**: :ref:`🔗` .. _class_@GlobalScope_constant_MOUSE_BUTTON_NONE: @@ -2525,7 +2523,7 @@ Extra mouse button 2. This is sometimes present, usually to the sides of the mou .. rst-class:: classref-enumeration -flags **MouseButtonMask**: +flags **MouseButtonMask**: :ref:`🔗` .. _class_@GlobalScope_constant_MOUSE_BUTTON_MASK_LEFT: @@ -2575,7 +2573,7 @@ Extra mouse button 2 mask. .. rst-class:: classref-enumeration -enum **JoyButton**: +enum **JoyButton**: :ref:`🔗` .. _class_@GlobalScope_constant_JOY_BUTTON_INVALID: @@ -2783,7 +2781,7 @@ The maximum number of game controller buttons supported by the engine. The actua .. rst-class:: classref-enumeration -enum **JoyAxis**: +enum **JoyAxis**: :ref:`🔗` .. _class_@GlobalScope_constant_JOY_AXIS_INVALID: @@ -2865,7 +2863,7 @@ The maximum number of game controller axes: OpenVR supports up to 5 Joysticks ma .. rst-class:: classref-enumeration -enum **MIDIMessage**: +enum **MIDIMessage**: :ref:`🔗` .. _class_@GlobalScope_constant_MIDI_MESSAGE_NONE: @@ -3037,7 +3035,7 @@ MIDI message sent to reset a MIDI device to its default state, as if it was just .. rst-class:: classref-enumeration -enum **Error**: +enum **Error**: :ref:`🔗` .. _class_@GlobalScope_constant_OK: @@ -3047,16 +3045,14 @@ enum **Error**: Methods that return :ref:`Error` return :ref:`OK` when no error occurred. -Since :ref:`OK` has value 0, and all other error constants are positive integers, it can also be used in boolean checks. - -\ **Example:**\ +Since :ref:`OK` has value ``0``, and all other error constants are positive integers, it can also be used in boolean checks. :: var error = method_that_returns_error() if error != OK: printerr("Failure!") - + # Or, alternatively: if error: printerr("Still failing!") @@ -3457,7 +3453,7 @@ Printer on fire error (This is an easter egg, no built-in methods return this er .. rst-class:: classref-enumeration -enum **PropertyHint**: +enum **PropertyHint**: :ref:`🔗` .. _class_@GlobalScope_constant_PROPERTY_HINT_NONE: @@ -3591,7 +3587,7 @@ Hints that an integer property is a bitmask using the optionally named avoidance :ref:`PropertyHint` **PROPERTY_HINT_FILE** = ``13`` -Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. +Hints that a :ref:`String` property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. By default the file will be stored as UID whenever available. You can use :ref:`ResourceUID` methods to convert it back to path. For storing a raw path, use :ref:`PROPERTY_HINT_FILE_PATH`. .. _class_@GlobalScope_constant_PROPERTY_HINT_DIR: @@ -3675,6 +3671,8 @@ If a property is :ref:`String`, hints that the property represents If a property is :ref:`Array`, hints the editor how to show elements. The ``hint_string`` must encode nested types using ``":"`` and ``"/"``. +If a property is :ref:`Dictionary`, hints the editor how to show elements. The ``hint_string`` is the same as :ref:`Array`, with a ``";"`` separating the key and value. + .. tabs:: @@ -3704,7 +3702,7 @@ If a property is :ref:`Array`, hints the editor how to show element -Examples: +\ **Examples:**\ .. tabs:: @@ -3717,7 +3715,7 @@ Examples: hint_string = "%d/%d:Zero,One,Three:3,Six:6" % [TYPE_INT, PROPERTY_HINT_ENUM] # Array of integers (an enum). hint_string = "%d/%d:*.png" % [TYPE_STRING, PROPERTY_HINT_FILE] # Array of strings (file paths). hint_string = "%d/%d:Texture2D" % [TYPE_OBJECT, PROPERTY_HINT_RESOURCE_TYPE] # Array of textures. - + hint_string = "%d:%d:" % [TYPE_ARRAY, TYPE_FLOAT] # Two-dimensional array of floats. hint_string = "%d:%d/%d:" % [TYPE_ARRAY, TYPE_STRING, PROPERTY_HINT_MULTILINE_TEXT] # Two-dimensional array of multiline strings. hint_string = "%d:%d/%d:-1,1,0.1" % [TYPE_ARRAY, TYPE_FLOAT, PROPERTY_HINT_RANGE] # Two-dimensional array of floats (in range from -1 to 1). @@ -3730,7 +3728,7 @@ Examples: hintString = $"{Variant.Type.Int:D}/{PropertyHint.Enum:D}:Zero,One,Three:3,Six:6"; // Array of integers (an enum). hintString = $"{Variant.Type.String:D}/{PropertyHint.File:D}:*.png"; // Array of strings (file paths). hintString = $"{Variant.Type.Object:D}/{PropertyHint.ResourceType:D}:Texture2D"; // Array of textures. - + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Float:D}:"; // Two-dimensional array of floats. hintString = $"{Variant.Type.Array:D}:{Variant.Type.String:D}/{PropertyHint.MultilineText:D}:"; // Two-dimensional array of multiline strings. hintString = $"{Variant.Type.Array:D}:{Variant.Type.Float:D}/{PropertyHint.Range:D}:-1,1,0.1"; // Two-dimensional array of floats (in range from -1 to 1). @@ -3806,7 +3804,19 @@ Hints that an :ref:`int` property is a pointer. Used by GDExtension. :ref:`PropertyHint` **PROPERTY_HINT_ARRAY_TYPE** = ``31`` -Hints that a property is an :ref:`Array` with the stored type specified in the hint string. +Hints that a property is an :ref:`Array` with the stored type specified in the hint string. The hint string contains the type of the array (e.g. ``"String"``). + +Use the hint string format from :ref:`PROPERTY_HINT_TYPE_STRING` for more control over the stored type. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_DICTIONARY_TYPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_DICTIONARY_TYPE** = ``38`` + +Hints that a property is a :ref:`Dictionary` with the stored types specified in the hint string. The hint string contains the key and value types separated by a semicolon (e.g. ``"int;String"``). + +Use the hint string format from :ref:`PROPERTY_HINT_TYPE_STRING` for more control over the stored types. .. _class_@GlobalScope_constant_PROPERTY_HINT_LOCALE_ID: @@ -3848,11 +3858,64 @@ Hints that a quaternion property should disable the temporary euler editor. Hints that a string property is a password, and every character is replaced with the secret character. +.. _class_@GlobalScope_constant_PROPERTY_HINT_TOOL_BUTTON: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_TOOL_BUTTON** = ``39`` + +Hints that a :ref:`Callable` property should be displayed as a clickable button. When the button is pressed, the callable is called. The hint string specifies the button text and optionally an icon from the ``"EditorIcons"`` theme type. + +.. code:: text + + "Click me!" - A button with the text "Click me!" and the default "Callable" icon. + "Click me!,ColorRect" - A button with the text "Click me!" and the "ColorRect" icon. + +\ **Note:** A :ref:`Callable` cannot be properly serialized and stored in a file, so it is recommended to use :ref:`PROPERTY_USAGE_EDITOR` instead of :ref:`PROPERTY_USAGE_DEFAULT`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_ONESHOT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_ONESHOT** = ``40`` + +Hints that a property will be changed on its own after setting, such as :ref:`AudioStreamPlayer.playing` or :ref:`GPUParticles3D.emitting`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_GROUP_ENABLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_GROUP_ENABLE** = ``42`` + +Hints that a boolean property will enable the feature associated with the group that it occurs in. The property will be displayed as a checkbox on the group header. Only works within a group or subgroup. + +By default, disabling the property hides all properties in the group. Use the optional hint string ``"checkbox_only"`` to disable this behavior. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_INPUT_NAME: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_INPUT_NAME** = ``43`` + +Hints that a :ref:`String` or :ref:`StringName` property is the name of an input action. This allows the selection of any action name from the Input Map in the Project Settings. The hint string may contain two options separated by commas: + +- If it contains ``"show_builtin"``, built-in input actions are included in the selection. + +- If it contains ``"loose_mode"``, loose mode is enabled. This allows inserting any action name even if it's not present in the input map. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_FILE_PATH: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_FILE_PATH** = ``44`` + +Like :ref:`PROPERTY_HINT_FILE`, but the property is stored as a raw path, not UID. That means the reference will be broken if you move the file. Consider using :ref:`PROPERTY_HINT_FILE` when possible. + .. _class_@GlobalScope_constant_PROPERTY_HINT_MAX: .. rst-class:: classref-enumeration-constant -:ref:`PropertyHint` **PROPERTY_HINT_MAX** = ``38`` +:ref:`PropertyHint` **PROPERTY_HINT_MAX** = ``45`` Represents the size of the :ref:`PropertyHint` enum. @@ -3864,7 +3927,7 @@ Represents the size of the :ref:`PropertyHint` e .. rst-class:: classref-enumeration -flags **PropertyUsageFlags**: +flags **PropertyUsageFlags**: :ref:`🔗` .. _class_@GlobalScope_constant_PROPERTY_USAGE_NONE: @@ -3880,7 +3943,7 @@ The property is not stored, and does not display in the editor. This is the defa :ref:`PropertyUsageFlags` **PROPERTY_USAGE_STORAGE** = ``2`` -The property is serialized and saved in the scene file (default). +The property is serialized and saved in the scene file (default for exported properties). .. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR: @@ -3888,7 +3951,7 @@ The property is serialized and saved in the scene file (default). :ref:`PropertyUsageFlags` **PROPERTY_USAGE_EDITOR** = ``4`` -The property is shown in the :ref:`EditorInspector` (default). +The property is shown in the :ref:`EditorInspector` (default for exported properties). .. _class_@GlobalScope_constant_PROPERTY_USAGE_INTERNAL: @@ -3968,7 +4031,7 @@ Editing the property prompts the user for restarting the editor. :ref:`PropertyUsageFlags` **PROPERTY_USAGE_SCRIPT_VARIABLE** = ``4096`` -The property is a script variable which should be serialized and saved in the scene file. +The property is a script variable. :ref:`PROPERTY_USAGE_SCRIPT_VARIABLE` can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, :ref:`PROPERTY_USAGE_SCRIPT_VARIABLE` is **not** applied to variables that are created by overriding :ref:`Object._get_property_list()` in a script. .. _class_@GlobalScope_constant_PROPERTY_USAGE_STORE_IF_NULL: @@ -4002,7 +4065,7 @@ If this property is modified, all inspector fields will be refreshed. :ref:`PropertyUsageFlags` **PROPERTY_USAGE_CLASS_IS_ENUM** = ``65536`` -The property is an enum, i.e. it only takes named integer constants from its associated enumeration. +The property is a variable of enum type, i.e. it only takes named integer constants from its associated enumeration. .. _class_@GlobalScope_constant_PROPERTY_USAGE_NIL_IS_VARIANT: @@ -4026,7 +4089,7 @@ The property is an array. :ref:`PropertyUsageFlags` **PROPERTY_USAGE_ALWAYS_DUPLICATE** = ``524288`` -When duplicating a resource with :ref:`Resource.duplicate`, and this flag is set on a property of that resource, the property should always be duplicated, regardless of the ``subresources`` bool parameter. +When duplicating a resource with :ref:`Resource.duplicate()`, and this flag is set on a property of that resource, the property should always be duplicated, regardless of the ``subresources`` bool parameter. .. _class_@GlobalScope_constant_PROPERTY_USAGE_NEVER_DUPLICATE: @@ -4034,7 +4097,7 @@ When duplicating a resource with :ref:`Resource.duplicate` **PROPERTY_USAGE_NEVER_DUPLICATE** = ``1048576`` -When duplicating a resource with :ref:`Resource.duplicate`, and this flag is set on a property of that resource, the property should never be duplicated, regardless of the ``subresources`` bool parameter. +When duplicating a resource with :ref:`Resource.duplicate()`, and this flag is set on a property of that resource, the property should never be duplicated, regardless of the ``subresources`` bool parameter. .. _class_@GlobalScope_constant_PROPERTY_USAGE_HIGH_END_GFX: @@ -4134,7 +4197,7 @@ Default usage but without showing the property in the editor (storage). .. rst-class:: classref-enumeration -flags **MethodFlags**: +flags **MethodFlags**: :ref:`🔗` .. _class_@GlobalScope_constant_METHOD_FLAG_NORMAL: @@ -4190,7 +4253,15 @@ Flag for a static method. :ref:`MethodFlags` **METHOD_FLAG_OBJECT_CORE** = ``64`` -Used internally. Allows to not dump core virtual methods (such as :ref:`Object._notification`) to the JSON API. +Used internally. Allows to not dump core virtual methods (such as :ref:`Object._notification()`) to the JSON API. + +.. _class_@GlobalScope_constant_METHOD_FLAG_VIRTUAL_REQUIRED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MethodFlags` **METHOD_FLAG_VIRTUAL_REQUIRED** = ``128`` + +Flag for a virtual method that is required. In GDScript, this flag is set for abstract functions. .. _class_@GlobalScope_constant_METHOD_FLAGS_DEFAULT: @@ -4208,7 +4279,7 @@ Default method flags (normal). .. rst-class:: classref-enumeration -enum **Variant.Type**: +enum **Variant.Type**: :ref:`🔗` .. _class_@GlobalScope_constant_TYPE_NIL: @@ -4514,11 +4585,19 @@ Variable is of type :ref:`PackedVector3Array`. Variable is of type :ref:`PackedColorArray`. +.. _class_@GlobalScope_constant_TYPE_PACKED_VECTOR4_ARRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`Variant.Type` **TYPE_PACKED_VECTOR4_ARRAY** = ``38`` + +Variable is of type :ref:`PackedVector4Array`. + .. _class_@GlobalScope_constant_TYPE_MAX: .. rst-class:: classref-enumeration-constant -:ref:`Variant.Type` **TYPE_MAX** = ``38`` +:ref:`Variant.Type` **TYPE_MAX** = ``39`` Represents the size of the :ref:`Variant.Type` enum. @@ -4530,7 +4609,7 @@ Represents the size of the :ref:`Variant.Type` e .. rst-class:: classref-enumeration -enum **Variant.Operator**: +enum **Variant.Operator**: :ref:`🔗` .. _class_@GlobalScope_constant_OP_EQUAL: @@ -4753,7 +4832,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`AudioServer` **AudioServer** +:ref:`AudioServer` **AudioServer** :ref:`🔗` The :ref:`AudioServer` singleton. @@ -4765,7 +4844,7 @@ The :ref:`AudioServer` singleton. .. rst-class:: classref-property -:ref:`CameraServer` **CameraServer** +:ref:`CameraServer` **CameraServer** :ref:`🔗` The :ref:`CameraServer` singleton. @@ -4777,7 +4856,7 @@ The :ref:`CameraServer` singleton. .. rst-class:: classref-property -:ref:`ClassDB` **ClassDB** +:ref:`ClassDB` **ClassDB** :ref:`🔗` The :ref:`ClassDB` singleton. @@ -4789,7 +4868,7 @@ The :ref:`ClassDB` singleton. .. rst-class:: classref-property -:ref:`DisplayServer` **DisplayServer** +:ref:`DisplayServer` **DisplayServer** :ref:`🔗` The :ref:`DisplayServer` singleton. @@ -4801,7 +4880,7 @@ The :ref:`DisplayServer` singleton. .. rst-class:: classref-property -:ref:`EditorInterface` **EditorInterface** +:ref:`EditorInterface` **EditorInterface** :ref:`🔗` The :ref:`EditorInterface` singleton. @@ -4815,7 +4894,7 @@ The :ref:`EditorInterface` singleton. .. rst-class:: classref-property -:ref:`Engine` **Engine** +:ref:`Engine` **Engine** :ref:`🔗` The :ref:`Engine` singleton. @@ -4827,7 +4906,7 @@ The :ref:`Engine` singleton. .. rst-class:: classref-property -:ref:`EngineDebugger` **EngineDebugger** +:ref:`EngineDebugger` **EngineDebugger** :ref:`🔗` The :ref:`EngineDebugger` singleton. @@ -4839,7 +4918,7 @@ The :ref:`EngineDebugger` singleton. .. rst-class:: classref-property -:ref:`GDExtensionManager` **GDExtensionManager** +:ref:`GDExtensionManager` **GDExtensionManager** :ref:`🔗` The :ref:`GDExtensionManager` singleton. @@ -4851,7 +4930,7 @@ The :ref:`GDExtensionManager` singleton. .. rst-class:: classref-property -:ref:`Geometry2D` **Geometry2D** +:ref:`Geometry2D` **Geometry2D** :ref:`🔗` The :ref:`Geometry2D` singleton. @@ -4863,7 +4942,7 @@ The :ref:`Geometry2D` singleton. .. rst-class:: classref-property -:ref:`Geometry3D` **Geometry3D** +:ref:`Geometry3D` **Geometry3D** :ref:`🔗` The :ref:`Geometry3D` singleton. @@ -4871,23 +4950,11 @@ The :ref:`Geometry3D` singleton. ---- -.. _class_@GlobalScope_property_GodotSharp: - -.. rst-class:: classref-property - -:ref:`GodotSharp` **GodotSharp** - -The :ref:`GodotSharp` singleton. - -.. rst-class:: classref-item-separator - ----- - .. _class_@GlobalScope_property_IP: .. rst-class:: classref-property -:ref:`IP` **IP** +:ref:`IP` **IP** :ref:`🔗` The :ref:`IP` singleton. @@ -4899,7 +4966,7 @@ The :ref:`IP` singleton. .. rst-class:: classref-property -:ref:`Input` **Input** +:ref:`Input` **Input** :ref:`🔗` The :ref:`Input` singleton. @@ -4911,7 +4978,7 @@ The :ref:`Input` singleton. .. rst-class:: classref-property -:ref:`InputMap` **InputMap** +:ref:`InputMap` **InputMap** :ref:`🔗` The :ref:`InputMap` singleton. @@ -4923,7 +4990,7 @@ The :ref:`InputMap` singleton. .. rst-class:: classref-property -:ref:`JavaClassWrapper` **JavaClassWrapper** +:ref:`JavaClassWrapper` **JavaClassWrapper** :ref:`🔗` The :ref:`JavaClassWrapper` singleton. @@ -4937,7 +5004,7 @@ The :ref:`JavaClassWrapper` singleton. .. rst-class:: classref-property -:ref:`JavaScriptBridge` **JavaScriptBridge** +:ref:`JavaScriptBridge` **JavaScriptBridge** :ref:`🔗` The :ref:`JavaScriptBridge` singleton. @@ -4951,7 +5018,7 @@ The :ref:`JavaScriptBridge` singleton. .. rst-class:: classref-property -:ref:`Marshalls` **Marshalls** +:ref:`Marshalls` **Marshalls** :ref:`🔗` The :ref:`Marshalls` singleton. @@ -4963,7 +5030,7 @@ The :ref:`Marshalls` singleton. .. rst-class:: classref-property -:ref:`NativeMenu` **NativeMenu** +:ref:`NativeMenu` **NativeMenu** :ref:`🔗` The :ref:`NativeMenu` singleton. @@ -4977,7 +5044,7 @@ The :ref:`NativeMenu` singleton. .. rst-class:: classref-property -:ref:`NavigationMeshGenerator` **NavigationMeshGenerator** +:ref:`NavigationMeshGenerator` **NavigationMeshGenerator** :ref:`🔗` The :ref:`NavigationMeshGenerator` singleton. @@ -4989,7 +5056,7 @@ The :ref:`NavigationMeshGenerator` singleton. .. rst-class:: classref-property -:ref:`NavigationServer2D` **NavigationServer2D** +:ref:`NavigationServer2D` **NavigationServer2D** :ref:`🔗` The :ref:`NavigationServer2D` singleton. @@ -5001,7 +5068,7 @@ The :ref:`NavigationServer2D` singleton. .. rst-class:: classref-property -:ref:`NavigationServer3D` **NavigationServer3D** +:ref:`NavigationServer3D` **NavigationServer3D** :ref:`🔗` The :ref:`NavigationServer3D` singleton. @@ -5013,7 +5080,7 @@ The :ref:`NavigationServer3D` singleton. .. rst-class:: classref-property -:ref:`OS` **OS** +:ref:`OS` **OS** :ref:`🔗` The :ref:`OS` singleton. @@ -5025,7 +5092,7 @@ The :ref:`OS` singleton. .. rst-class:: classref-property -:ref:`Performance` **Performance** +:ref:`Performance` **Performance** :ref:`🔗` The :ref:`Performance` singleton. @@ -5037,7 +5104,7 @@ The :ref:`Performance` singleton. .. rst-class:: classref-property -:ref:`PhysicsServer2D` **PhysicsServer2D** +:ref:`PhysicsServer2D` **PhysicsServer2D** :ref:`🔗` The :ref:`PhysicsServer2D` singleton. @@ -5049,7 +5116,7 @@ The :ref:`PhysicsServer2D` singleton. .. rst-class:: classref-property -:ref:`PhysicsServer2DManager` **PhysicsServer2DManager** +:ref:`PhysicsServer2DManager` **PhysicsServer2DManager** :ref:`🔗` The :ref:`PhysicsServer2DManager` singleton. @@ -5061,7 +5128,7 @@ The :ref:`PhysicsServer2DManager` singleton. .. rst-class:: classref-property -:ref:`PhysicsServer3D` **PhysicsServer3D** +:ref:`PhysicsServer3D` **PhysicsServer3D** :ref:`🔗` The :ref:`PhysicsServer3D` singleton. @@ -5073,7 +5140,7 @@ The :ref:`PhysicsServer3D` singleton. .. rst-class:: classref-property -:ref:`PhysicsServer3DManager` **PhysicsServer3DManager** +:ref:`PhysicsServer3DManager` **PhysicsServer3DManager** :ref:`🔗` The :ref:`PhysicsServer3DManager` singleton. @@ -5085,7 +5152,7 @@ The :ref:`PhysicsServer3DManager` singleton. .. rst-class:: classref-property -:ref:`ProjectSettings` **ProjectSettings** +:ref:`ProjectSettings` **ProjectSettings** :ref:`🔗` The :ref:`ProjectSettings` singleton. @@ -5097,7 +5164,7 @@ The :ref:`ProjectSettings` singleton. .. rst-class:: classref-property -:ref:`RenderingServer` **RenderingServer** +:ref:`RenderingServer` **RenderingServer** :ref:`🔗` The :ref:`RenderingServer` singleton. @@ -5109,7 +5176,7 @@ The :ref:`RenderingServer` singleton. .. rst-class:: classref-property -:ref:`ResourceLoader` **ResourceLoader** +:ref:`ResourceLoader` **ResourceLoader** :ref:`🔗` The :ref:`ResourceLoader` singleton. @@ -5121,7 +5188,7 @@ The :ref:`ResourceLoader` singleton. .. rst-class:: classref-property -:ref:`ResourceSaver` **ResourceSaver** +:ref:`ResourceSaver` **ResourceSaver** :ref:`🔗` The :ref:`ResourceSaver` singleton. @@ -5133,7 +5200,7 @@ The :ref:`ResourceSaver` singleton. .. rst-class:: classref-property -:ref:`ResourceUID` **ResourceUID** +:ref:`ResourceUID` **ResourceUID** :ref:`🔗` The :ref:`ResourceUID` singleton. @@ -5145,7 +5212,7 @@ The :ref:`ResourceUID` singleton. .. rst-class:: classref-property -:ref:`TextServerManager` **TextServerManager** +:ref:`TextServerManager` **TextServerManager** :ref:`🔗` The :ref:`TextServerManager` singleton. @@ -5157,7 +5224,7 @@ The :ref:`TextServerManager` singleton. .. rst-class:: classref-property -:ref:`ThemeDB` **ThemeDB** +:ref:`ThemeDB` **ThemeDB** :ref:`🔗` The :ref:`ThemeDB` singleton. @@ -5169,7 +5236,7 @@ The :ref:`ThemeDB` singleton. .. rst-class:: classref-property -:ref:`Time` **Time** +:ref:`Time` **Time** :ref:`🔗` The :ref:`Time` singleton. @@ -5181,7 +5248,7 @@ The :ref:`Time` singleton. .. rst-class:: classref-property -:ref:`TranslationServer` **TranslationServer** +:ref:`TranslationServer` **TranslationServer** :ref:`🔗` The :ref:`TranslationServer` singleton. @@ -5193,7 +5260,7 @@ The :ref:`TranslationServer` singleton. .. rst-class:: classref-property -:ref:`WorkerThreadPool` **WorkerThreadPool** +:ref:`WorkerThreadPool` **WorkerThreadPool** :ref:`🔗` The :ref:`WorkerThreadPool` singleton. @@ -5205,7 +5272,7 @@ The :ref:`WorkerThreadPool` singleton. .. rst-class:: classref-property -:ref:`XRServer` **XRServer** +:ref:`XRServer` **XRServer** :ref:`🔗` The :ref:`XRServer` singleton. @@ -5222,7 +5289,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Variant` **abs**\ (\ x\: :ref:`Variant`\ ) +:ref:`Variant` **abs**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` Returns the absolute value of a :ref:`Variant` parameter ``x`` (i.e. non-negative value). Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. @@ -5230,23 +5297,23 @@ Returns the absolute value of a :ref:`Variant` parameter ``x`` (i var a = abs(-1) # a is 1 - + var b = abs(-1.2) # b is 1.2 - + var c = abs(Vector2(-3.5, -4)) # c is (3.5, 4) - + var d = abs(Vector2i(-5, -6)) # d is (5, 6) - + var e = abs(Vector3(-7, 8.5, -3.8)) # e is (7, 8.5, 3.8) - + var f = abs(Vector3i(-7, -8, -9)) # f is (7, 8, 9) -\ **Note:** For better type safety, use :ref:`absf`, :ref:`absi`, :ref:`Vector2.abs`, :ref:`Vector2i.abs`, :ref:`Vector3.abs`, :ref:`Vector3i.abs`, :ref:`Vector4.abs`, or :ref:`Vector4i.abs`. +\ **Note:** For better type safety, use :ref:`absf()`, :ref:`absi()`, :ref:`Vector2.abs()`, :ref:`Vector2i.abs()`, :ref:`Vector3.abs()`, :ref:`Vector3i.abs()`, :ref:`Vector4.abs()`, or :ref:`Vector4i.abs()`. .. rst-class:: classref-item-separator @@ -5256,7 +5323,7 @@ Returns the absolute value of a :ref:`Variant` parameter ``x`` (i .. rst-class:: classref-method -:ref:`float` **absf**\ (\ x\: :ref:`float`\ ) +:ref:`float` **absf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the absolute value of float parameter ``x`` (i.e. positive value). @@ -5273,7 +5340,7 @@ Returns the absolute value of float parameter ``x`` (i.e. positive value). .. rst-class:: classref-method -:ref:`int` **absi**\ (\ x\: :ref:`int`\ ) +:ref:`int` **absi**\ (\ x\: :ref:`int`\ ) :ref:`🔗` Returns the absolute value of int parameter ``x`` (i.e. positive value). @@ -5290,9 +5357,9 @@ Returns the absolute value of int parameter ``x`` (i.e. positive value). .. rst-class:: classref-method -:ref:`float` **acos**\ (\ x\: :ref:`float`\ ) +:ref:`float` **acos**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`acos` from returning :ref:`@GDScript.NAN`. +Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`acos()` from returning :ref:`@GDScript.NAN`. :: @@ -5307,15 +5374,15 @@ Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x`` .. rst-class:: classref-method -:ref:`float` **acosh**\ (\ x\: :ref:`float`\ ) +:ref:`float` **acosh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -Returns the hyperbolic arc (also called inverse) cosine of ``x``, returning a value in radians. Use it to get the angle from an angle's cosine in hyperbolic space if ``x`` is larger or equal to 1. For values of ``x`` lower than 1, it will return 0, in order to prevent :ref:`acosh` from returning :ref:`@GDScript.NAN`. +Returns the hyperbolic arc (also called inverse) cosine of ``x``, returning a value in radians. Use it to get the angle from an angle's cosine in hyperbolic space if ``x`` is larger or equal to 1. For values of ``x`` lower than 1, it will return 0, in order to prevent :ref:`acosh()` from returning :ref:`@GDScript.NAN`. :: var a = acosh(2) # Returns 1.31695789692482 cosh(a) # Returns 2 - + var b = acosh(-1) # Returns 0 .. rst-class:: classref-item-separator @@ -5326,9 +5393,9 @@ Returns the hyperbolic arc (also called inverse) cosine of ``x``, returning a va .. rst-class:: classref-method -:ref:`float` **angle_difference**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) +:ref:`float` **angle_difference**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) :ref:`🔗` -Returns the difference between the two angles, in the range of ``[-PI, +PI]``. When ``from`` and ``to`` are opposite, returns ``-PI`` if ``from`` is smaller than ``to``, or ``PI`` otherwise. +Returns the difference between the two angles (in radians), in the range of ``[-PI, +PI]``. When ``from`` and ``to`` are opposite, returns ``-PI`` if ``from`` is smaller than ``to``, or ``PI`` otherwise. .. rst-class:: classref-item-separator @@ -5338,9 +5405,9 @@ Returns the difference between the two angles, in the range of ``[-PI, +PI]``. W .. rst-class:: classref-method -:ref:`float` **asin**\ (\ x\: :ref:`float`\ ) +:ref:`float` **asin**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -Returns the arc sine of ``x`` in radians. Use to get the angle of sine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`asin` from returning :ref:`@GDScript.NAN`. +Returns the arc sine of ``x`` in radians. Use to get the angle of sine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`asin()` from returning :ref:`@GDScript.NAN`. :: @@ -5355,7 +5422,7 @@ Returns the arc sine of ``x`` in radians. Use to get the angle of sine ``x``. `` .. rst-class:: classref-method -:ref:`float` **asinh**\ (\ x\: :ref:`float`\ ) +:ref:`float` **asinh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the hyperbolic arc (also called inverse) sine of ``x``, returning a value in radians. Use it to get the angle from an angle's sine in hyperbolic space. @@ -5372,11 +5439,11 @@ Returns the hyperbolic arc (also called inverse) sine of ``x``, returning a valu .. rst-class:: classref-method -:ref:`float` **atan**\ (\ x\: :ref:`float`\ ) +:ref:`float` **atan**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the arc tangent of ``x`` in radians. Use it to get the angle from an angle's tangent in trigonometry. -The method cannot know in which quadrant the angle should fall. See :ref:`atan2` if you have both ``y`` and ``x``. +The method cannot know in which quadrant the angle should fall. See :ref:`atan2()` if you have both ``y`` and ``x``. :: @@ -5392,7 +5459,7 @@ If ``x`` is between ``-PI / 2`` and ``PI / 2`` (inclusive), ``atan(tan(x))`` is .. rst-class:: classref-method -:ref:`float` **atan2**\ (\ y\: :ref:`float`, x\: :ref:`float`\ ) +:ref:`float` **atan2**\ (\ y\: :ref:`float`, x\: :ref:`float`\ ) :ref:`🔗` Returns the arc tangent of ``y/x`` in radians. Use to get the angle of tangent ``y/x``. To compute the value, the method takes into account the sign of both arguments in order to determine the quadrant. @@ -5410,17 +5477,17 @@ Important note: The Y coordinate comes first, by convention. .. rst-class:: classref-method -:ref:`float` **atanh**\ (\ x\: :ref:`float`\ ) +:ref:`float` **atanh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the hyperbolic arc (also called inverse) tangent of ``x``, returning a value in radians. Use it to get the angle from an angle's tangent in hyperbolic space if ``x`` is between -1 and 1 (non-inclusive). -In mathematics, the inverse hyperbolic tangent is only defined for -1 < ``x`` < 1 in the real set, so values equal or lower to -1 for ``x`` return negative :ref:`@GDScript.INF` and values equal or higher than 1 return positive :ref:`@GDScript.INF` in order to prevent :ref:`atanh` from returning :ref:`@GDScript.NAN`. +In mathematics, the inverse hyperbolic tangent is only defined for -1 < ``x`` < 1 in the real set, so values equal or lower to -1 for ``x`` return negative :ref:`@GDScript.INF` and values equal or higher than 1 return positive :ref:`@GDScript.INF` in order to prevent :ref:`atanh()` from returning :ref:`@GDScript.NAN`. :: var a = atanh(0.9) # Returns 1.47221948958322 tanh(a) # Returns 0.9 - + var b = atanh(-2) # Returns -inf tanh(b) # Returns -1 @@ -5432,7 +5499,7 @@ In mathematics, the inverse hyperbolic tangent is only defined for -1 < ``x`` < .. rst-class:: classref-method -:ref:`float` **bezier_derivative**\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) +:ref:`float` **bezier_derivative**\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) :ref:`🔗` Returns the derivative at the given ``t`` on a one-dimensional `Bézier curve `__ defined by the given ``control_1``, ``control_2``, and ``end`` points. @@ -5444,7 +5511,7 @@ Returns the derivative at the given ``t`` on a one-dimensional `Bézier curve ` **bezier_interpolate**\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) +:ref:`float` **bezier_interpolate**\ (\ start\: :ref:`float`, control_1\: :ref:`float`, control_2\: :ref:`float`, end\: :ref:`float`, t\: :ref:`float`\ ) :ref:`🔗` Returns the point at the given ``t`` on a one-dimensional `Bézier curve `__ defined by the given ``control_1``, ``control_2``, and ``end`` points. @@ -5456,11 +5523,11 @@ Returns the point at the given ``t`` on a one-dimensional `Bézier curve ` **bytes_to_var**\ (\ bytes\: :ref:`PackedByteArray`\ ) +:ref:`Variant` **bytes_to_var**\ (\ bytes\: :ref:`PackedByteArray`\ ) :ref:`🔗` Decodes a byte array back to a :ref:`Variant` value, without decoding objects. -\ **Note:** If you need object deserialization, see :ref:`bytes_to_var_with_objects`. +\ **Note:** If you need object deserialization, see :ref:`bytes_to_var_with_objects()`. .. rst-class:: classref-item-separator @@ -5470,7 +5537,7 @@ Decodes a byte array back to a :ref:`Variant` value, without deco .. rst-class:: classref-method -:ref:`Variant` **bytes_to_var_with_objects**\ (\ bytes\: :ref:`PackedByteArray`\ ) +:ref:`Variant` **bytes_to_var_with_objects**\ (\ bytes\: :ref:`PackedByteArray`\ ) :ref:`🔗` Decodes a byte array back to a :ref:`Variant` value. Decoding objects is allowed. @@ -5484,7 +5551,7 @@ Decodes a byte array back to a :ref:`Variant` value. Decoding obj .. rst-class:: classref-method -:ref:`Variant` **ceil**\ (\ x\: :ref:`Variant`\ ) +:ref:`Variant` **ceil**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. @@ -5493,9 +5560,9 @@ Rounds ``x`` upward (towards positive infinity), returning the smallest whole nu var i = ceil(1.45) # i is 2.0 i = ceil(1.001) # i is 2.0 -See also :ref:`floor`, :ref:`round`, and :ref:`snapped`. +See also :ref:`floor()`, :ref:`round()`, and :ref:`snapped()`. -\ **Note:** For better type safety, use :ref:`ceilf`, :ref:`ceili`, :ref:`Vector2.ceil`, :ref:`Vector3.ceil`, or :ref:`Vector4.ceil`. +\ **Note:** For better type safety, use :ref:`ceilf()`, :ref:`ceili()`, :ref:`Vector2.ceil()`, :ref:`Vector3.ceil()`, or :ref:`Vector4.ceil()`. .. rst-class:: classref-item-separator @@ -5505,11 +5572,11 @@ See also :ref:`floor`, :ref:`round` **ceilf**\ (\ x\: :ref:`float`\ ) +:ref:`float` **ceilf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. -A type-safe version of :ref:`ceil`, returning a :ref:`float`. +A type-safe version of :ref:`ceil()`, returning a :ref:`float`. .. rst-class:: classref-item-separator @@ -5519,11 +5586,11 @@ A type-safe version of :ref:`ceil`, returning a .. rst-class:: classref-method -:ref:`int` **ceili**\ (\ x\: :ref:`float`\ ) +:ref:`int` **ceili**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Rounds ``x`` upward (towards positive infinity), returning the smallest whole number that is not less than ``x``. -A type-safe version of :ref:`ceil`, returning an :ref:`int`. +A type-safe version of :ref:`ceil()`, returning an :ref:`int`. .. rst-class:: classref-item-separator @@ -5533,7 +5600,7 @@ A type-safe version of :ref:`ceil`, returning an .. rst-class:: classref-method -:ref:`Variant` **clamp**\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) +:ref:`Variant` **clamp**\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) :ref:`🔗` 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. @@ -5541,11 +5608,11 @@ Clamps the ``value``, returning a :ref:`Variant` not less than `` var a = clamp(-10, -1, 5) # a is -1 - + var b = clamp(8.1, 0.9, 5.5) # b is 5.5 -\ **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` (not currently supported by this method). +\ **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()` (not currently supported by this method). \ **Note:** When using this on vectors it will *not* perform component-wise clamping, and will pick ``min`` if ``value < min`` or ``max`` if ``value > max``. To perform component-wise clamping use the methods listed above. @@ -5557,7 +5624,7 @@ Clamps the ``value``, returning a :ref:`Variant` not less than `` .. rst-class:: classref-method -:ref:`float` **clampf**\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) +:ref:`float` **clampf**\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) :ref:`🔗` Clamps the ``value``, returning a :ref:`float` not less than ``min`` and not more than ``max``. @@ -5565,7 +5632,7 @@ Clamps the ``value``, returning a :ref:`float` not less than ``min` var speed = 42.1 var a = clampf(speed, 1.0, 20.5) # a is 20.5 - + speed = -10.0 var b = clampf(speed, -1.0, 1.0) # b is -1.0 @@ -5577,7 +5644,7 @@ Clamps the ``value``, returning a :ref:`float` not less than ``min` .. rst-class:: classref-method -:ref:`int` **clampi**\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) +:ref:`int` **clampi**\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) :ref:`🔗` Clamps the ``value``, returning an :ref:`int` not less than ``min`` and not more than ``max``. @@ -5585,7 +5652,7 @@ Clamps the ``value``, returning an :ref:`int` not less than ``min`` a var speed = 42 var a = clampi(speed, 1, 20) # a is 20 - + speed = -10 var b = clampi(speed, -1, 1) # b is -1 @@ -5597,7 +5664,7 @@ Clamps the ``value``, returning an :ref:`int` not less than ``min`` a .. rst-class:: classref-method -:ref:`float` **cos**\ (\ angle_rad\: :ref:`float`\ ) +:ref:`float` **cos**\ (\ angle_rad\: :ref:`float`\ ) :ref:`🔗` Returns the cosine of angle ``angle_rad`` in radians. @@ -5615,7 +5682,7 @@ Returns the cosine of angle ``angle_rad`` in radians. .. rst-class:: classref-method -:ref:`float` **cosh**\ (\ x\: :ref:`float`\ ) +:ref:`float` **cosh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the hyperbolic cosine of ``x`` in radians. @@ -5631,7 +5698,7 @@ Returns the hyperbolic cosine of ``x`` in radians. .. rst-class:: classref-method -:ref:`float` **cubic_interpolate**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) +:ref:`float` **cubic_interpolate**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` Cubic interpolates between two values by the factor defined in ``weight`` with ``pre`` and ``post`` values. @@ -5643,9 +5710,9 @@ Cubic interpolates between two values by the factor defined in ``weight`` with ` .. rst-class:: classref-method -:ref:`float` **cubic_interpolate_angle**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) +:ref:`float` **cubic_interpolate_angle**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` -Cubic interpolates between two rotation values with shortest path by the factor defined in ``weight`` with ``pre`` and ``post`` values. See also :ref:`lerp_angle`. +Cubic interpolates between two rotation values with shortest path by the factor defined in ``weight`` with ``pre`` and ``post`` values. See also :ref:`lerp_angle()`. .. rst-class:: classref-item-separator @@ -5655,11 +5722,11 @@ Cubic interpolates between two rotation values with shortest path by the factor .. rst-class:: classref-method -:ref:`float` **cubic_interpolate_angle_in_time**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) +:ref:`float` **cubic_interpolate_angle_in_time**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) :ref:`🔗` -Cubic interpolates between two rotation values with shortest path by the factor defined in ``weight`` with ``pre`` and ``post`` values. See also :ref:`lerp_angle`. +Cubic interpolates between two rotation values with shortest path by the factor defined in ``weight`` with ``pre`` and ``post`` values. See also :ref:`lerp_angle()`. -It can perform smoother interpolation than :ref:`cubic_interpolate` by the time values. +It can perform smoother interpolation than :ref:`cubic_interpolate()` by the time values. .. rst-class:: classref-item-separator @@ -5669,11 +5736,11 @@ It can perform smoother interpolation than :ref:`cubic_interpolate` **cubic_interpolate_in_time**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) +:ref:`float` **cubic_interpolate_in_time**\ (\ from\: :ref:`float`, to\: :ref:`float`, pre\: :ref:`float`, post\: :ref:`float`, weight\: :ref:`float`, to_t\: :ref:`float`, pre_t\: :ref:`float`, post_t\: :ref:`float`\ ) :ref:`🔗` Cubic interpolates between two values by the factor defined in ``weight`` with ``pre`` and ``post`` values. -It can perform smoother interpolation than :ref:`cubic_interpolate` by the time values. +It can perform smoother interpolation than :ref:`cubic_interpolate()` by the time values. .. rst-class:: classref-item-separator @@ -5683,7 +5750,7 @@ It can perform smoother interpolation than :ref:`cubic_interpolate` **db_to_linear**\ (\ db\: :ref:`float`\ ) +:ref:`float` **db_to_linear**\ (\ db\: :ref:`float`\ ) :ref:`🔗` Converts from decibels to linear energy (audio). @@ -5695,7 +5762,7 @@ Converts from decibels to linear energy (audio). .. rst-class:: classref-method -:ref:`float` **deg_to_rad**\ (\ deg\: :ref:`float`\ ) +:ref:`float` **deg_to_rad**\ (\ deg\: :ref:`float`\ ) :ref:`🔗` Converts an angle expressed in degrees to radians. @@ -5711,14 +5778,14 @@ Converts an angle expressed in degrees to radians. .. rst-class:: classref-method -:ref:`float` **ease**\ (\ x\: :ref:`float`, curve\: :ref:`float`\ ) +:ref:`float` **ease**\ (\ x\: :ref:`float`, curve\: :ref:`float`\ ) :ref:`🔗` Returns an "eased" value of ``x`` based on an easing function defined with ``curve``. This easing function is based on an exponent. The ``curve`` can be any floating-point number, with specific values leading to the following behaviors: -:: +.. code:: text - Lower than -1.0 (exclusive): Ease in-out - - 1.0: Linear + - -1.0: Linear - Between -1.0 and 0.0 (exclusive): Ease out-in - 0.0: Constant - Between 0.0 to 1.0 (exclusive): Ease out @@ -5727,7 +5794,7 @@ Returns an "eased" value of ``x`` based on an easing function defined with ``cur \ `ease() curve values cheatsheet `__\ -See also :ref:`smoothstep`. If you need to perform more advanced transitions, use :ref:`Tween.interpolate_value`. +See also :ref:`smoothstep()`. If you need to perform more advanced transitions, use :ref:`Tween.interpolate_value()`. .. rst-class:: classref-item-separator @@ -5737,16 +5804,16 @@ See also :ref:`smoothstep`. If you need to .. rst-class:: classref-method -:ref:`String` **error_string**\ (\ error\: :ref:`int`\ ) +:ref:`String` **error_string**\ (\ error\: :ref:`int`\ ) :ref:`🔗` Returns a human-readable name for the given :ref:`Error` code. :: print(OK) # Prints 0 - print(error_string(OK)) # Prints OK - print(error_string(ERR_BUSY)) # Prints Busy - print(error_string(ERR_OUT_OF_MEMORY)) # Prints Out of memory + print(error_string(OK)) # Prints "OK" + print(error_string(ERR_BUSY)) # Prints "Busy" + print(error_string(ERR_OUT_OF_MEMORY)) # Prints "Out of memory" .. rst-class:: classref-item-separator @@ -5756,13 +5823,13 @@ Returns a human-readable name for the given :ref:`Error .. rst-class:: classref-method -:ref:`float` **exp**\ (\ x\: :ref:`float`\ ) +:ref:`float` **exp**\ (\ x\: :ref:`float`\ ) :ref:`🔗` The natural exponential function. It raises the mathematical constant *e* to the power of ``x`` and returns it. \ *e* has an approximate value of 2.71828, and can be obtained with ``exp(1)``. -For exponents to other bases use the method :ref:`pow`. +For exponents to other bases use the method :ref:`pow()`. :: @@ -5776,7 +5843,7 @@ For exponents to other bases use the method :ref:`pow` **floor**\ (\ x\: :ref:`Variant`\ ) +:ref:`Variant` **floor**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. @@ -5785,9 +5852,9 @@ Rounds ``x`` downward (towards negative infinity), returning the largest whole n var a = floor(2.99) # a is 2.0 a = floor(-2.99) # a is -3.0 -See also :ref:`ceil`, :ref:`round`, and :ref:`snapped`. +See also :ref:`ceil()`, :ref:`round()`, and :ref:`snapped()`. -\ **Note:** For better type safety, use :ref:`floorf`, :ref:`floori`, :ref:`Vector2.floor`, :ref:`Vector3.floor`, or :ref:`Vector4.floor`. +\ **Note:** For better type safety, use :ref:`floorf()`, :ref:`floori()`, :ref:`Vector2.floor()`, :ref:`Vector3.floor()`, or :ref:`Vector4.floor()`. .. rst-class:: classref-item-separator @@ -5797,11 +5864,11 @@ See also :ref:`ceil`, :ref:`round` **floorf**\ (\ x\: :ref:`float`\ ) +:ref:`float` **floorf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. -A type-safe version of :ref:`floor`, returning a :ref:`float`. +A type-safe version of :ref:`floor()`, returning a :ref:`float`. .. rst-class:: classref-item-separator @@ -5811,11 +5878,11 @@ A type-safe version of :ref:`floor`, returning .. rst-class:: classref-method -:ref:`int` **floori**\ (\ x\: :ref:`float`\ ) +:ref:`int` **floori**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Rounds ``x`` downward (towards negative infinity), returning the largest whole number that is not more than ``x``. -A type-safe version of :ref:`floor`, returning an :ref:`int`. +A type-safe version of :ref:`floor()`, returning an :ref:`int`. \ **Note:** This function is *not* the same as ``int(x)``, which rounds towards 0. @@ -5827,7 +5894,7 @@ A type-safe version of :ref:`floor`, returning .. rst-class:: classref-method -:ref:`float` **fmod**\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) +:ref:`float` **fmod**\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) :ref:`🔗` Returns the floating-point remainder of ``x`` divided by ``y``, keeping the sign of ``x``. @@ -5845,7 +5912,7 @@ For the integer remainder operation, use the ``%`` operator. .. rst-class:: classref-method -:ref:`float` **fposmod**\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) +:ref:`float` **fposmod**\ (\ x\: :ref:`float`, y\: :ref:`float`\ ) :ref:`🔗` Returns the floating-point modulus of ``x`` divided by ``y``, wrapping equally in positive and negative. @@ -5856,9 +5923,9 @@ Returns the floating-point modulus of ``x`` divided by ``y``, wrapping equally i var x = i * 0.5 - 1.5 print("%4.1f %4.1f | %4.1f" % [x, fmod(x, 1.5), fposmod(x, 1.5)]) -Produces: +Prints: -:: +.. code:: text (x) (fmod(x, 1.5)) (fposmod(x, 1.5)) -1.5 -0.0 | 0.0 @@ -5877,7 +5944,7 @@ Produces: .. rst-class:: classref-method -:ref:`int` **hash**\ (\ variable\: :ref:`Variant`\ ) +:ref:`int` **hash**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` Returns the integer hash of the passed ``variable``. @@ -5902,33 +5969,33 @@ Returns the integer hash of the passed ``variable``. .. rst-class:: classref-method -:ref:`Object` **instance_from_id**\ (\ instance_id\: :ref:`int`\ ) +:ref:`Object` **instance_from_id**\ (\ instance_id\: :ref:`int`\ ) :ref:`🔗` -Returns the :ref:`Object` that corresponds to ``instance_id``. All Objects have a unique instance ID. See also :ref:`Object.get_instance_id`. +Returns the :ref:`Object` that corresponds to ``instance_id``. All Objects have a unique instance ID. See also :ref:`Object.get_instance_id()`. .. tabs:: .. code-tab:: gdscript - var foo = "bar" - + var drink = "water" + func _ready(): var id = get_instance_id() - var inst = instance_from_id(id) - print(inst.foo) # Prints bar + var instance = instance_from_id(id) + print(instance.foo) # Prints "water" .. code-tab:: csharp public partial class MyNode : Node { - public string Foo { get; set; } = "bar"; - + public string Drink { get; set; } = "water"; + public override void _Ready() { ulong id = GetInstanceId(); - var inst = (MyNode)InstanceFromId(Id); - GD.Print(inst.Foo); // Prints bar + var instance = (MyNode)InstanceFromId(Id); + GD.Print(instance.Drink); // Prints "water" } } @@ -5942,21 +6009,21 @@ Returns the :ref:`Object` that corresponds to ``instance_id``. All .. rst-class:: classref-method -:ref:`float` **inverse_lerp**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) +:ref:`float` **inverse_lerp**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` -Returns an interpolation or extrapolation factor considering the range specified in ``from`` and ``to``, and the interpolated value specified in ``weight``. The returned value will be between ``0.0`` and ``1.0`` if ``weight`` is between ``from`` and ``to`` (inclusive). If ``weight`` is located outside this range, then an extrapolation factor will be returned (return value lower than ``0.0`` or greater than ``1.0``). Use :ref:`clamp` on the result of :ref:`inverse_lerp` if this is not desired. +Returns an interpolation or extrapolation factor considering the range specified in ``from`` and ``to``, and the interpolated value specified in ``weight``. The returned value will be between ``0.0`` and ``1.0`` if ``weight`` is between ``from`` and ``to`` (inclusive). If ``weight`` is located outside this range, then an extrapolation factor will be returned (return value lower than ``0.0`` or greater than ``1.0``). Use :ref:`clamp()` on the result of :ref:`inverse_lerp()` if this is not desired. :: # The interpolation ratio in the `lerp()` call below is 0.75. var middle = lerp(20, 30, 0.75) # middle is now 27.5. - + # Now, we pretend to have forgotten the original ratio and want to get it back. var ratio = inverse_lerp(20, 30, 27.5) # ratio is now 0.75. -See also :ref:`lerp`, which performs the reverse of this operation, and :ref:`remap` to map a continuous series of values to another. +See also :ref:`lerp()`, which performs the reverse of this operation, and :ref:`remap()` to map a continuous series of values to another. .. rst-class:: classref-item-separator @@ -5966,7 +6033,7 @@ See also :ref:`lerp`, which performs the reverse .. rst-class:: classref-method -:ref:`bool` **is_equal_approx**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) +:ref:`bool` **is_equal_approx**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) :ref:`🔗` Returns ``true`` if ``a`` and ``b`` are approximately equal to each other. @@ -5982,9 +6049,9 @@ Infinity values of the same sign are considered equal. .. rst-class:: classref-method -:ref:`bool` **is_finite**\ (\ x\: :ref:`float`\ ) +:ref:`bool` **is_finite**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -Returns whether ``x`` is a finite value, i.e. it is not :ref:`@GDScript.NAN`, positive infinity, or negative infinity. +Returns whether ``x`` is a finite value, i.e. it is not :ref:`@GDScript.NAN`, positive infinity, or negative infinity. See also :ref:`is_inf()` and :ref:`is_nan()`. .. rst-class:: classref-item-separator @@ -5994,9 +6061,9 @@ Returns whether ``x`` is a finite value, i.e. it is not :ref:`@GDScript.NAN` **is_inf**\ (\ x\: :ref:`float`\ ) +:ref:`bool` **is_inf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -Returns ``true`` if ``x`` is either positive infinity or negative infinity. +Returns ``true`` if ``x`` is either positive infinity or negative infinity. See also :ref:`is_finite()` and :ref:`is_nan()`. .. rst-class:: classref-item-separator @@ -6006,7 +6073,7 @@ Returns ``true`` if ``x`` is either positive infinity or negative infinity. .. rst-class:: classref-method -:ref:`bool` **is_instance_id_valid**\ (\ id\: :ref:`int`\ ) +:ref:`bool` **is_instance_id_valid**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Returns ``true`` if the Object that corresponds to ``id`` is a valid object (e.g. has not been deleted from memory). All Objects have a unique instance ID. @@ -6018,7 +6085,7 @@ Returns ``true`` if the Object that corresponds to ``id`` is a valid object (e.g .. rst-class:: classref-method -:ref:`bool` **is_instance_valid**\ (\ instance\: :ref:`Variant`\ ) +:ref:`bool` **is_instance_valid**\ (\ instance\: :ref:`Variant`\ ) :ref:`🔗` Returns ``true`` if ``instance`` is a valid Object (e.g. has not been deleted from memory). @@ -6030,9 +6097,9 @@ Returns ``true`` if ``instance`` is a valid Object (e.g. has not been deleted fr .. rst-class:: classref-method -:ref:`bool` **is_nan**\ (\ x\: :ref:`float`\ ) +:ref:`bool` **is_nan**\ (\ x\: :ref:`float`\ ) :ref:`🔗` -Returns ``true`` if ``x`` is a NaN ("Not a Number" or invalid) value. +Returns ``true`` if ``x`` is a NaN ("Not a Number" or invalid) value. This method is needed as :ref:`@GDScript.NAN` is not equal to itself, which means ``x == NAN`` can't be used to check whether a value is a NaN. .. rst-class:: classref-item-separator @@ -6042,7 +6109,7 @@ Returns ``true`` if ``x`` is a NaN ("Not a Number" or invalid) value. .. rst-class:: classref-method -:ref:`bool` **is_same**\ (\ a\: :ref:`Variant`, b\: :ref:`Variant`\ ) +:ref:`bool` **is_same**\ (\ a\: :ref:`Variant`, b\: :ref:`Variant`\ ) :ref:`🔗` Returns ``true``, for value types, if ``a`` and ``b`` share the same value. Returns ``true``, for reference types, if the references of ``a`` and ``b`` are the same. @@ -6055,7 +6122,7 @@ Returns ``true``, for value types, if ``a`` and ``b`` share the same value. Retu is_same(vec2_a, vec2_a) # true is_same(vec2_a, vec2_b) # true is_same(vec2_a, vec2_c) # false - + # Array is a reference type var arr_a = [] var arr_b = [] @@ -6064,7 +6131,7 @@ Returns ``true``, for value types, if ``a`` and ``b`` share the same value. Retu These are :ref:`Variant` value types: ``null``, :ref:`bool`, :ref:`int`, :ref:`float`, :ref:`String`, :ref:`StringName`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`, :ref:`Rect2`, :ref:`Rect2i`, :ref:`Transform2D`, :ref:`Transform3D`, :ref:`Plane`, :ref:`Quaternion`, :ref:`AABB`, :ref:`Basis`, :ref:`Projection`, :ref:`Color`, :ref:`NodePath`, :ref:`RID`, :ref:`Callable` and :ref:`Signal`. -These are :ref:`Variant` reference types: :ref:`Object`, :ref:`Dictionary`, :ref:`Array`, :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, :ref:`PackedFloat32Array`, :ref:`PackedFloat64Array`, :ref:`PackedStringArray`, :ref:`PackedVector2Array`, :ref:`PackedVector3Array` and :ref:`PackedColorArray`. +These are :ref:`Variant` reference types: :ref:`Object`, :ref:`Dictionary`, :ref:`Array`, :ref:`PackedByteArray`, :ref:`PackedInt32Array`, :ref:`PackedInt64Array`, :ref:`PackedFloat32Array`, :ref:`PackedFloat64Array`, :ref:`PackedStringArray`, :ref:`PackedVector2Array`, :ref:`PackedVector3Array`, :ref:`PackedVector4Array`, and :ref:`PackedColorArray`. .. rst-class:: classref-item-separator @@ -6074,11 +6141,11 @@ These are :ref:`Variant` reference types: :ref:`Object` **is_zero_approx**\ (\ x\: :ref:`float`\ ) +:ref:`bool` **is_zero_approx**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns ``true`` if ``x`` is zero or almost zero. The comparison is done using a tolerance calculation with a small internal epsilon. -This function is faster than using :ref:`is_equal_approx` with one value as zero. +This function is faster than using :ref:`is_equal_approx()` with one value as zero. .. rst-class:: classref-item-separator @@ -6088,19 +6155,19 @@ This function is faster than using :ref:`is_equal_approx` **lerp**\ (\ from\: :ref:`Variant`, to\: :ref:`Variant`, weight\: :ref:`Variant`\ ) +:ref:`Variant` **lerp**\ (\ from\: :ref:`Variant`, to\: :ref:`Variant`, weight\: :ref:`Variant`\ ) :ref:`🔗` -Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clamp` on the result of this function. +Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clampf()` to limit ``weight``. -Both ``from`` and ``to`` must be the same type. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`, :ref:`Color`, :ref:`Quaternion`, :ref:`Basis`. +Both ``from`` and ``to`` must be the same type. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`, :ref:`Color`, :ref:`Quaternion`, :ref:`Basis`, :ref:`Transform2D`, :ref:`Transform3D`. :: lerp(0, 4, 0.75) # Returns 3.0 -See also :ref:`inverse_lerp` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp`, combine it with :ref:`ease` or :ref:`smoothstep`. See also :ref:`remap` to map a continuous series of values to another. +See also :ref:`inverse_lerp()` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp()`, combine it with :ref:`ease()` or :ref:`smoothstep()`. See also :ref:`remap()` to map a continuous series of values to another. -\ **Note:** For better type safety, use :ref:`lerpf`, :ref:`Vector2.lerp`, :ref:`Vector3.lerp`, :ref:`Vector4.lerp`, :ref:`Color.lerp`, :ref:`Quaternion.slerp` or :ref:`Basis.slerp`. +\ **Note:** For better type safety, use :ref:`lerpf()`, :ref:`Vector2.lerp()`, :ref:`Vector3.lerp()`, :ref:`Vector4.lerp()`, :ref:`Color.lerp()`, :ref:`Quaternion.slerp()`, :ref:`Basis.slerp()`, :ref:`Transform2D.interpolate_with()`, or :ref:`Transform3D.interpolate_with()`. .. rst-class:: classref-item-separator @@ -6110,11 +6177,11 @@ See also :ref:`inverse_lerp` which perfo .. rst-class:: classref-method -:ref:`float` **lerp_angle**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) +:ref:`float` **lerp_angle**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` Linearly interpolates between two angles (in radians) by a ``weight`` value between 0.0 and 1.0. -Similar to :ref:`lerp`, but interpolates correctly when the angles wrap around :ref:`@GDScript.TAU`. To perform eased interpolation with :ref:`lerp_angle`, combine it with :ref:`ease` or :ref:`smoothstep`. +Similar to :ref:`lerp()`, but interpolates correctly when the angles wrap around :ref:`@GDScript.TAU`. To perform eased interpolation with :ref:`lerp_angle()`, combine it with :ref:`ease()` or :ref:`smoothstep()`. :: @@ -6136,15 +6203,15 @@ Similar to :ref:`lerp`, but interpolates correct .. rst-class:: classref-method -:ref:`float` **lerpf**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) +:ref:`float` **lerpf**\ (\ from\: :ref:`float`, to\: :ref:`float`, weight\: :ref:`float`\ ) :ref:`🔗` -Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clampf` on the result of this function. +Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clampf()` on the result of this function. :: lerpf(0, 4, 0.75) # Returns 3.0 -See also :ref:`inverse_lerp` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp`, combine it with :ref:`ease` or :ref:`smoothstep`. +See also :ref:`inverse_lerp()` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp()`, combine it with :ref:`ease()` or :ref:`smoothstep()`. .. rst-class:: classref-item-separator @@ -6154,17 +6221,14 @@ See also :ref:`inverse_lerp` which perfo .. rst-class:: classref-method -:ref:`float` **linear_to_db**\ (\ lin\: :ref:`float`\ ) +:ref:`float` **linear_to_db**\ (\ lin\: :ref:`float`\ ) :ref:`🔗` -Converts from linear energy to decibels (audio). This can be used to implement volume sliders that behave as expected (since volume isn't linear). +Converts from linear energy to decibels (audio). Since volume is not normally linear, this can be used to implement volume sliders that behave as expected. -\ **Example:**\ +\ **Example:** Change the Master bus's volume through a :ref:`Slider` node, which ranges from ``0.0`` to ``1.0``: :: - # "Slider" refers to a node that inherits Range such as HSlider or VSlider. - # Its range must be configured to go from 0 to 1. - # Change the bus name if you'd like to change the volume of a specific bus only. AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value)) .. rst-class:: classref-item-separator @@ -6175,7 +6239,7 @@ Converts from linear energy to decibels (audio). This can be used to implement v .. rst-class:: classref-method -:ref:`float` **log**\ (\ x\: :ref:`float`\ ) +:ref:`float` **log**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the `natural logarithm `__ of ``x`` (base `[i]e[/i] `__, with *e* being approximately 2.71828). This is the amount of time needed to reach a certain level of continuous growth. @@ -6195,7 +6259,7 @@ Returns the `natural logarithm .. rst-class:: classref-method -:ref:`Variant` **max**\ (\ ...\ ) |vararg| +:ref:`Variant` **max**\ (\ ...\ ) |vararg| :ref:`🔗` Returns the maximum of the given numeric values. This function can take any number of arguments. @@ -6203,6 +6267,8 @@ Returns the maximum of the given numeric values. This function can take any numb max(1, 7, 3, -6, 5) # Returns 7 +\ **Note:** When using this on vectors it will *not* perform component-wise maximum, and will pick the largest value when compared using ``x < y``. To perform component-wise maximum, use :ref:`Vector2.max()`, :ref:`Vector2i.max()`, :ref:`Vector3.max()`, :ref:`Vector3i.max()`, :ref:`Vector4.max()`, and :ref:`Vector4i.max()`. + .. rst-class:: classref-item-separator ---- @@ -6211,7 +6277,7 @@ Returns the maximum of the given numeric values. This function can take any numb .. rst-class:: classref-method -:ref:`float` **maxf**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) +:ref:`float` **maxf**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) :ref:`🔗` Returns the maximum of two :ref:`float` values. @@ -6228,7 +6294,7 @@ Returns the maximum of two :ref:`float` values. .. rst-class:: classref-method -:ref:`int` **maxi**\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) +:ref:`int` **maxi**\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) :ref:`🔗` Returns the maximum of two :ref:`int` values. @@ -6245,7 +6311,7 @@ Returns the maximum of two :ref:`int` values. .. rst-class:: classref-method -:ref:`Variant` **min**\ (\ ...\ ) |vararg| +:ref:`Variant` **min**\ (\ ...\ ) |vararg| :ref:`🔗` Returns the minimum of the given numeric values. This function can take any number of arguments. @@ -6253,6 +6319,8 @@ Returns the minimum of the given numeric values. This function can take any numb min(1, 7, 3, -6, 5) # Returns -6 +\ **Note:** When using this on vectors it will *not* perform component-wise minimum, and will pick the smallest value when compared using ``x < y``. To perform component-wise minimum, use :ref:`Vector2.min()`, :ref:`Vector2i.min()`, :ref:`Vector3.min()`, :ref:`Vector3i.min()`, :ref:`Vector4.min()`, and :ref:`Vector4i.min()`. + .. rst-class:: classref-item-separator ---- @@ -6261,7 +6329,7 @@ Returns the minimum of the given numeric values. This function can take any numb .. rst-class:: classref-method -:ref:`float` **minf**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) +:ref:`float` **minf**\ (\ a\: :ref:`float`, b\: :ref:`float`\ ) :ref:`🔗` Returns the minimum of two :ref:`float` values. @@ -6278,7 +6346,7 @@ Returns the minimum of two :ref:`float` values. .. rst-class:: classref-method -:ref:`int` **mini**\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) +:ref:`int` **mini**\ (\ a\: :ref:`int`, b\: :ref:`int`\ ) :ref:`🔗` Returns the minimum of two :ref:`int` values. @@ -6295,7 +6363,7 @@ Returns the minimum of two :ref:`int` values. .. rst-class:: classref-method -:ref:`float` **move_toward**\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) +:ref:`float` **move_toward**\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) :ref:`🔗` Moves ``from`` toward ``to`` by the ``delta`` amount. Will not go past ``to``. @@ -6316,7 +6384,7 @@ Use a negative ``delta`` value to move away. .. rst-class:: classref-method -:ref:`int` **nearest_po2**\ (\ value\: :ref:`int`\ ) +:ref:`int` **nearest_po2**\ (\ value\: :ref:`int`\ ) :ref:`🔗` Returns the smallest integer power of 2 that is greater than or equal to ``value``. @@ -6325,7 +6393,7 @@ Returns the smallest integer power of 2 that is greater than or equal to ``value nearest_po2(3) # Returns 4 nearest_po2(4) # Returns 4 nearest_po2(5) # Returns 8 - + nearest_po2(0) # Returns 0 (this may not be expected) nearest_po2(-1) # Returns 0 (this may not be expected) @@ -6339,7 +6407,7 @@ Returns the smallest integer power of 2 that is greater than or equal to ``value .. rst-class:: classref-method -:ref:`float` **pingpong**\ (\ value\: :ref:`float`, length\: :ref:`float`\ ) +:ref:`float` **pingpong**\ (\ value\: :ref:`float`, length\: :ref:`float`\ ) :ref:`🔗` Wraps ``value`` between ``0`` and the ``length``. If the limit is reached, the next value the function returns is decreased to the ``0`` side or increased to the ``length`` side (like a triangle wave). If ``length`` is less than zero, it becomes positive. @@ -6364,7 +6432,7 @@ Wraps ``value`` between ``0`` and the ``length``. If the limit is reached, the n .. rst-class:: classref-method -:ref:`int` **posmod**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) +:ref:`int` **posmod**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) :ref:`🔗` Returns the integer modulus of ``x`` divided by ``y`` that wraps equally in positive and negative. @@ -6374,9 +6442,9 @@ Returns the integer modulus of ``x`` divided by ``y`` that wraps equally in posi for i in range(-3, 4): print("%2d %2d | %2d" % [i, i % 3, posmod(i, 3)]) -Produces: +Prints: -:: +.. code:: text (i) (i % 3) (posmod(i, 3)) -3 0 | 0 @@ -6395,7 +6463,7 @@ Produces: .. rst-class:: classref-method -:ref:`float` **pow**\ (\ base\: :ref:`float`, exp\: :ref:`float`\ ) +:ref:`float` **pow**\ (\ base\: :ref:`float`, exp\: :ref:`float`\ ) :ref:`🔗` Returns the result of ``base`` raised to the power of ``exp``. @@ -6414,7 +6482,7 @@ In GDScript, this is the equivalent of the ``**`` operator. .. rst-class:: classref-method -|void| **print**\ (\ ...\ ) |vararg| +|void| **print**\ (\ ...\ ) |vararg| :ref:`🔗` Converts one or more arguments of any type to string in the best way possible and prints them to the console. @@ -6424,16 +6492,16 @@ Converts one or more arguments of any type to string in the best way possible an .. code-tab:: gdscript var a = [1, 2, 3] - print("a", "b", a) # Prints ab[1, 2, 3] + print("a", "b", a) # Prints "ab[1, 2, 3]" .. code-tab:: csharp - var a = new Godot.Collections.Array { 1, 2, 3 }; - GD.Print("a", "b", a); // Prints ab[1, 2, 3] + Godot.Collections.Array a = [1, 2, 3]; + GD.Print("a", "b", a); // Prints "ab[1, 2, 3]" -\ **Note:** Consider using :ref:`push_error` and :ref:`push_warning` to print error and warning messages instead of :ref:`print` or :ref:`print_rich`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. +\ **Note:** Consider using :ref:`push_error()` and :ref:`push_warning()` to print error and warning messages instead of :ref:`print()` or :ref:`print_rich()`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. See also :ref:`Engine.print_to_stdout` and :ref:`ProjectSettings.application/run/disable_stdout`. .. rst-class:: classref-item-separator @@ -6443,14 +6511,12 @@ Converts one or more arguments of any type to string in the best way possible an .. rst-class:: classref-method -|void| **print_rich**\ (\ ...\ ) |vararg| +|void| **print_rich**\ (\ ...\ ) |vararg| :ref:`🔗` Converts one or more arguments of any type to string in the best way possible and prints them to the console. The following BBCode tags are supported: ``b``, ``i``, ``u``, ``s``, ``indent``, ``code``, ``url``, ``center``, ``right``, ``color``, ``bgcolor``, ``fgcolor``. -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 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. @@ -6460,19 +6526,17 @@ When printing to standard output, the supported subset of BBCode is converted to .. code-tab:: gdscript - print_rich("[color=green][b]Hello world![/b][/color]") # Prints out "Hello world!" in green with a bold font + print_rich("[color=green][b]Hello world![/b][/color]") # Prints "Hello world!", in green with a bold font. .. code-tab:: csharp - GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints out "Hello world!" in green with a bold font + GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints "Hello world!", in green with a bold font. -\ **Note:** Consider using :ref:`push_error` and :ref:`push_warning` to print error and warning messages instead of :ref:`print` or :ref:`print_rich`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. +\ **Note:** Consider using :ref:`push_error()` and :ref:`push_warning()` to print error and warning messages instead of :ref:`print()` or :ref:`print_rich()`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. -\ **Note:** On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output. - -\ **Note:** Output displayed in the editor supports clickable ``[url=address]text[/url]`` tags. The ``[url]`` tag's ``address`` value is handled by :ref:`OS.shell_open` when clicked. +\ **Note:** Output displayed in the editor supports clickable ``[url=address]text[/url]`` tags. The ``[url]`` tag's ``address`` value is handled by :ref:`OS.shell_open()` when clicked. .. rst-class:: classref-item-separator @@ -6482,9 +6546,9 @@ When printing to standard output, the supported subset of BBCode is converted to .. rst-class:: classref-method -|void| **print_verbose**\ (\ ...\ ) |vararg| +|void| **print_verbose**\ (\ ...\ ) |vararg| :ref:`🔗` -If verbose mode is enabled (:ref:`OS.is_stdout_verbose` returning ``true``), converts one or more arguments of any type to string in the best way possible and prints them to the console. +If verbose mode is enabled (:ref:`OS.is_stdout_verbose()` returning ``true``), converts one or more arguments of any type to string in the best way possible and prints them to the console. .. rst-class:: classref-item-separator @@ -6494,7 +6558,7 @@ If verbose mode is enabled (:ref:`OS.is_stdout_verbose` Prints one or more arguments to strings in the best way possible to standard error line. @@ -6519,26 +6583,28 @@ Prints one or more arguments to strings in the best way possible to standard err .. rst-class:: classref-method -|void| **printraw**\ (\ ...\ ) |vararg| +|void| **printraw**\ (\ ...\ ) |vararg| :ref:`🔗` + +Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike :ref:`print()`, no newline is automatically added at the end. -Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike :ref:`print`, no newline is automatically added at the end. +\ **Note:** The OS terminal is *not* the same as the editor's Output dock. The output sent to the OS terminal can be seen when running Godot from a terminal. On Windows, this requires using the ``console.exe`` executable. .. tabs:: .. code-tab:: gdscript + # Prints "ABC" to terminal. printraw("A") printraw("B") printraw("C") - # Prints ABC to terminal .. code-tab:: csharp + // Prints "ABC" to terminal. GD.PrintRaw("A"); GD.PrintRaw("B"); GD.PrintRaw("C"); - // Prints ABC to terminal @@ -6550,7 +6616,7 @@ Prints one or more arguments to strings in the best way possible to the OS termi .. rst-class:: classref-method -|void| **prints**\ (\ ...\ ) |vararg| +|void| **prints**\ (\ ...\ ) |vararg| :ref:`🔗` Prints one or more arguments to the console with a space between each argument. @@ -6559,11 +6625,11 @@ Prints one or more arguments to the console with a space between each argument. .. code-tab:: gdscript - prints("A", "B", "C") # Prints A B C + prints("A", "B", "C") # Prints "A B C" .. code-tab:: csharp - GD.PrintS("A", "B", "C"); // Prints A B C + GD.PrintS("A", "B", "C"); // Prints "A B C" @@ -6575,7 +6641,7 @@ Prints one or more arguments to the console with a space between each argument. .. rst-class:: classref-method -|void| **printt**\ (\ ...\ ) |vararg| +|void| **printt**\ (\ ...\ ) |vararg| :ref:`🔗` Prints one or more arguments to the console with a tab between each argument. @@ -6584,11 +6650,11 @@ Prints one or more arguments to the console with a tab between each argument. .. code-tab:: gdscript - printt("A", "B", "C") # Prints A B C + printt("A", "B", "C") # Prints "A B C" .. code-tab:: csharp - GD.PrintT("A", "B", "C"); // Prints A B C + GD.PrintT("A", "B", "C"); // Prints "A B C" @@ -6600,7 +6666,7 @@ Prints one or more arguments to the console with a tab between each argument. .. rst-class:: classref-method -|void| **push_error**\ (\ ...\ ) |vararg| +|void| **push_error**\ (\ ...\ ) |vararg| :ref:`🔗` Pushes an error message to Godot's built-in debugger and to the OS terminal. @@ -6609,11 +6675,11 @@ Pushes an error message to Godot's built-in debugger and to the OS terminal. .. code-tab:: gdscript - push_error("test error") # Prints "test error" to debugger and terminal as error call + push_error("test error") # Prints "test error" to debugger and terminal as an error. .. code-tab:: csharp - GD.PushError("test error"); // Prints "test error" to debugger and terminal as error call + GD.PushError("test error"); // Prints "test error" to debugger and terminal as an error. @@ -6627,7 +6693,7 @@ Pushes an error message to Godot's built-in debugger and to the OS terminal. .. rst-class:: classref-method -|void| **push_warning**\ (\ ...\ ) |vararg| +|void| **push_warning**\ (\ ...\ ) |vararg| :ref:`🔗` Pushes a warning message to Godot's built-in debugger and to the OS terminal. @@ -6636,11 +6702,11 @@ Pushes a warning message to Godot's built-in debugger and to the OS terminal. .. code-tab:: gdscript - push_warning("test warning") # Prints "test warning" to debugger and terminal as warning call + push_warning("test warning") # Prints "test warning" to debugger and terminal as a warning. .. code-tab:: csharp - GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call + GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as a warning. @@ -6652,7 +6718,7 @@ Pushes a warning message to Godot's built-in debugger and to the OS terminal. .. rst-class:: classref-method -:ref:`float` **rad_to_deg**\ (\ rad\: :ref:`float`\ ) +:ref:`float` **rad_to_deg**\ (\ rad\: :ref:`float`\ ) :ref:`🔗` Converts an angle expressed in radians to degrees. @@ -6670,7 +6736,7 @@ Converts an angle expressed in radians to degrees. .. rst-class:: classref-method -:ref:`PackedInt64Array` **rand_from_seed**\ (\ seed\: :ref:`int`\ ) +:ref:`PackedInt64Array` **rand_from_seed**\ (\ seed\: :ref:`int`\ ) :ref:`🔗` Given a ``seed``, returns a :ref:`PackedInt64Array` of size ``2``, where its first element is the randomized :ref:`int` value, and the second element is the same as ``seed``. Passing the same ``seed`` consistently returns the same array. @@ -6679,9 +6745,9 @@ Given a ``seed``, returns a :ref:`PackedInt64Array` of s :: var a = rand_from_seed(4) - - print(a[0]) # Prints 2879024997 - print(a[1]) # Prints 4 + + print(a[0]) # Prints 2879024997 + print(a[1]) # Prints 4 .. rst-class:: classref-item-separator @@ -6691,7 +6757,7 @@ Given a ``seed``, returns a :ref:`PackedInt64Array` of s .. rst-class:: classref-method -:ref:`float` **randf**\ (\ ) +:ref:`float` **randf**\ (\ ) :ref:`🔗` Returns a random floating-point value between ``0.0`` and ``1.0`` (inclusive). @@ -6716,7 +6782,7 @@ Returns a random floating-point value between ``0.0`` and ``1.0`` (inclusive). .. rst-class:: classref-method -:ref:`float` **randf_range**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) +:ref:`float` **randf_range**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) :ref:`🔗` Returns a random floating-point value between ``from`` and ``to`` (inclusive). @@ -6743,7 +6809,7 @@ Returns a random floating-point value between ``from`` and ``to`` (inclusive). .. rst-class:: classref-method -:ref:`float` **randfn**\ (\ mean\: :ref:`float`, deviation\: :ref:`float`\ ) +:ref:`float` **randfn**\ (\ mean\: :ref:`float`, deviation\: :ref:`float`\ ) :ref:`🔗` Returns a `normally-distributed `__, pseudo-random floating-point value from the specified ``mean`` and a standard ``deviation``. This is also known as a Gaussian distribution. @@ -6757,7 +6823,7 @@ Returns a `normally-distributed ` **randi**\ (\ ) +:ref:`int` **randi**\ (\ ) :ref:`🔗` Returns a random unsigned 32-bit integer. Use remainder to obtain a random value in the interval ``[0, N - 1]`` (where N is smaller than 2^32). @@ -6788,7 +6854,7 @@ Returns a random unsigned 32-bit integer. Use remainder to obtain a random value .. rst-class:: classref-method -:ref:`int` **randi_range**\ (\ from\: :ref:`int`, to\: :ref:`int`\ ) +:ref:`int` **randi_range**\ (\ from\: :ref:`int`, to\: :ref:`int`\ ) :ref:`🔗` Returns a random signed 32-bit integer between ``from`` and ``to`` (inclusive). If ``to`` is lesser than ``from``, they are swapped. @@ -6815,11 +6881,11 @@ Returns a random signed 32-bit integer between ``from`` and ``to`` (inclusive). .. rst-class:: classref-method -|void| **randomize**\ (\ ) +|void| **randomize**\ (\ ) :ref:`🔗` Randomizes the seed (or the internal state) of the random number generator. The current implementation uses a number based on the device's time. -\ **Note:** This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use :ref:`seed` to initialize the random number generator. +\ **Note:** This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use :ref:`seed()` to initialize the random number generator. .. rst-class:: classref-item-separator @@ -6829,9 +6895,9 @@ Randomizes the seed (or the internal state) of the random number generator. The .. rst-class:: classref-method -:ref:`float` **remap**\ (\ value\: :ref:`float`, istart\: :ref:`float`, istop\: :ref:`float`, ostart\: :ref:`float`, ostop\: :ref:`float`\ ) +:ref:`float` **remap**\ (\ value\: :ref:`float`, istart\: :ref:`float`, istop\: :ref:`float`, ostart\: :ref:`float`, ostop\: :ref:`float`\ ) :ref:`🔗` -Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``. See also :ref:`lerp` and :ref:`inverse_lerp`. If ``value`` is outside ``[istart, istop]``, then the resulting value will also be outside ``[ostart, ostop]``. If this is not desired, use :ref:`clamp` on the result of this function. +Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``. See also :ref:`lerp()` and :ref:`inverse_lerp()`. If ``value`` is outside ``[istart, istop]``, then the resulting value will also be outside ``[ostart, ostop]``. If this is not desired, use :ref:`clamp()` on the result of this function. :: @@ -6839,6 +6905,8 @@ Maps a ``value`` from range ``[istart, istop]`` to ``[ostart, ostop]``. See also For complex use cases where multiple ranges are needed, consider using :ref:`Curve` or :ref:`Gradient` instead. +\ **Note:** If ``istart == istop``, the return value is undefined (most likely NaN, INF, or -INF). + .. rst-class:: classref-item-separator ---- @@ -6847,9 +6915,9 @@ For complex use cases where multiple ranges are needed, consider using :ref:`Cur .. rst-class:: classref-method -:ref:`int` **rid_allocate_id**\ (\ ) +:ref:`int` **rid_allocate_id**\ (\ ) :ref:`🔗` -Allocates a unique ID which can be used by the implementation to construct a RID. This is used mainly from native extensions to implement servers. +Allocates a unique ID which can be used by the implementation to construct an RID. This is used mainly from native extensions to implement servers. .. rst-class:: classref-item-separator @@ -6859,9 +6927,9 @@ Allocates a unique ID which can be used by the implementation to construct a RID .. rst-class:: classref-method -:ref:`RID` **rid_from_int64**\ (\ base\: :ref:`int`\ ) +:ref:`RID` **rid_from_int64**\ (\ base\: :ref:`int`\ ) :ref:`🔗` -Creates a RID from a ``base``. This is used mainly from native extensions to build servers. +Creates an RID from a ``base``. This is used mainly from native extensions to build servers. .. rst-class:: classref-item-separator @@ -6871,11 +6939,11 @@ Creates a RID from a ``base``. This is used mainly from native extensions to bui .. rst-class:: classref-method -:ref:`float` **rotate_toward**\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) +:ref:`float` **rotate_toward**\ (\ from\: :ref:`float`, to\: :ref:`float`, delta\: :ref:`float`\ ) :ref:`🔗` Rotates ``from`` toward ``to`` by the ``delta`` amount. Will not go past ``to``. -Similar to :ref:`move_toward`, but interpolates correctly when the angles wrap around :ref:`@GDScript.TAU`. +Similar to :ref:`move_toward()`, but interpolates correctly when the angles wrap around :ref:`@GDScript.TAU`. If ``delta`` is negative, this function will rotate away from ``to``, toward the opposite angle, and will not go past the opposite angle. @@ -6887,7 +6955,7 @@ If ``delta`` is negative, this function will rotate away from ``to``, toward the .. rst-class:: classref-method -:ref:`Variant` **round**\ (\ x\: :ref:`Variant`\ ) +:ref:`Variant` **round**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector2i`, :ref:`Vector3`, :ref:`Vector3i`, :ref:`Vector4`, :ref:`Vector4i`. @@ -6897,9 +6965,9 @@ Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0 round(2.5) # Returns 3 round(2.6) # Returns 3 -See also :ref:`floor`, :ref:`ceil`, and :ref:`snapped`. +See also :ref:`floor()`, :ref:`ceil()`, and :ref:`snapped()`. -\ **Note:** For better type safety, use :ref:`roundf`, :ref:`roundi`, :ref:`Vector2.round`, :ref:`Vector3.round`, or :ref:`Vector4.round`. +\ **Note:** For better type safety, use :ref:`roundf()`, :ref:`roundi()`, :ref:`Vector2.round()`, :ref:`Vector3.round()`, or :ref:`Vector4.round()`. .. rst-class:: classref-item-separator @@ -6909,11 +6977,11 @@ See also :ref:`floor`, :ref:`ceil` **roundf**\ (\ x\: :ref:`float`\ ) +:ref:`float` **roundf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. -A type-safe version of :ref:`round`, returning a :ref:`float`. +A type-safe version of :ref:`round()`, returning a :ref:`float`. .. rst-class:: classref-item-separator @@ -6923,11 +6991,11 @@ A type-safe version of :ref:`round`, returning .. rst-class:: classref-method -:ref:`int` **roundi**\ (\ x\: :ref:`float`\ ) +:ref:`int` **roundi**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Rounds ``x`` to the nearest whole number, with halfway cases rounded away from 0. -A type-safe version of :ref:`round`, returning an :ref:`int`. +A type-safe version of :ref:`round()`, returning an :ref:`int`. .. rst-class:: classref-item-separator @@ -6937,7 +7005,7 @@ A type-safe version of :ref:`round`, returning .. rst-class:: classref-method -|void| **seed**\ (\ base\: :ref:`int`\ ) +|void| **seed**\ (\ base\: :ref:`int`\ ) :ref:`🔗` Sets the seed for the random number generator to ``base``. Setting the seed manually can ensure consistent, repeatable results for most random functions. @@ -6972,7 +7040,7 @@ Sets the seed for the random number generator to ``base``. Setting the seed manu .. rst-class:: classref-method -:ref:`Variant` **sign**\ (\ x\: :ref:`Variant`\ ) +:ref:`Variant` **sign**\ (\ x\: :ref:`Variant`\ ) :ref:`🔗` Returns the same type of :ref:`Variant` as ``x``, with ``-1`` for negative values, ``1`` for positive values, and ``0`` for zeros. For ``nan`` values it returns 0. @@ -6984,10 +7052,10 @@ Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2 sign(0.0) # Returns 0 sign(6.0) # Returns 1 sign(NAN) # Returns 0 - + sign(Vector3(-6.0, 0.0, 6.0)) # Returns (-1, 0, 1) -\ **Note:** For better type safety, use :ref:`signf`, :ref:`signi`, :ref:`Vector2.sign`, :ref:`Vector2i.sign`, :ref:`Vector3.sign`, :ref:`Vector3i.sign`, :ref:`Vector4.sign`, or :ref:`Vector4i.sign`. +\ **Note:** For better type safety, use :ref:`signf()`, :ref:`signi()`, :ref:`Vector2.sign()`, :ref:`Vector2i.sign()`, :ref:`Vector3.sign()`, :ref:`Vector3i.sign()`, :ref:`Vector4.sign()`, or :ref:`Vector4i.sign()`. .. rst-class:: classref-item-separator @@ -6997,7 +7065,7 @@ Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2 .. rst-class:: classref-method -:ref:`float` **signf**\ (\ x\: :ref:`float`\ ) +:ref:`float` **signf**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns ``-1.0`` if ``x`` is negative, ``1.0`` if ``x`` is positive, and ``0.0`` if ``x`` is zero. For ``nan`` values of ``x`` it returns 0.0. @@ -7016,9 +7084,9 @@ Returns ``-1.0`` if ``x`` is negative, ``1.0`` if ``x`` is positive, and ``0.0`` .. rst-class:: classref-method -:ref:`int` **signi**\ (\ x\: :ref:`int`\ ) +:ref:`int` **signi**\ (\ x\: :ref:`int`\ ) :ref:`🔗` -Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if if ``x`` is zero. +Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if ``x`` is zero. :: @@ -7034,7 +7102,7 @@ Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if if .. rst-class:: classref-method -:ref:`float` **sin**\ (\ angle_rad\: :ref:`float`\ ) +:ref:`float` **sin**\ (\ angle_rad\: :ref:`float`\ ) :ref:`🔗` Returns the sine of angle ``angle_rad`` in radians. @@ -7051,7 +7119,7 @@ Returns the sine of angle ``angle_rad`` in radians. .. rst-class:: classref-method -:ref:`float` **sinh**\ (\ x\: :ref:`float`\ ) +:ref:`float` **sinh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the hyperbolic sine of ``x``. @@ -7068,11 +7136,13 @@ Returns the hyperbolic sine of ``x``. .. rst-class:: classref-method -:ref:`float` **smoothstep**\ (\ from\: :ref:`float`, to\: :ref:`float`, x\: :ref:`float`\ ) +:ref:`float` **smoothstep**\ (\ from\: :ref:`float`, to\: :ref:`float`, x\: :ref:`float`\ ) :ref:`🔗` + +Returns a smooth cubic Hermite interpolation between ``0`` and ``1``. -Returns the result of smoothly interpolating the value of ``x`` between ``0`` and ``1``, based on the where ``x`` lies with respect to the edges ``from`` and ``to``. +For positive ranges (when ``from <= to``) the return value is ``0`` when ``x <= from``, and ``1`` when ``x >= to``. If ``x`` lies between ``from`` and ``to``, the return value follows an S-shaped curve that smoothly transitions from ``0`` to ``1``. -The return value is ``0`` if ``x <= from``, and ``1`` if ``x >= to``. If ``x`` lies between ``from`` and ``to``, the returned value follows an S-shaped curve that maps ``x`` between ``0`` and ``1``. +For negative ranges (when ``from > to``) the function is mirrored and returns ``1`` when ``x <= to`` and ``0`` when ``x >= from``. This S-shaped curve is the cubic Hermite interpolator, given by ``f(y) = 3*y^2 - 2*y^3`` where ``y = (x-from) / (to-from)``. @@ -7083,9 +7153,11 @@ This S-shaped curve is the cubic Hermite interpolator, given by ``f(y) = 3*y^2 - smoothstep(0, 2, 1.0) # Returns 0.5 smoothstep(0, 2, 2.0) # Returns 1.0 -Compared to :ref:`ease` with a curve value of ``-1.6521``, :ref:`smoothstep` returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use :ref:`Tween` or :ref:`AnimationPlayer`. +Compared to :ref:`ease()` with a curve value of ``-1.6521``, :ref:`smoothstep()` returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use :ref:`Tween` or :ref:`AnimationPlayer`. -\ `Comparison between smoothstep() and ease(x, -1.6521) return values `__ +\ `Comparison between smoothstep() and ease(x, -1.6521) return values `__\ + +\ `Smoothstep() return values with positive, zero, and negative ranges `__ .. rst-class:: classref-item-separator @@ -7095,7 +7167,7 @@ Compared to :ref:`ease` with a curve value of `` .. rst-class:: classref-method -:ref:`Variant` **snapped**\ (\ x\: :ref:`Variant`, step\: :ref:`Variant`\ ) +:ref:`Variant` **snapped**\ (\ x\: :ref:`Variant`, step\: :ref:`Variant`\ ) :ref:`🔗` Returns the multiple of ``step`` that is the closest to ``x``. This can also be used to round a floating-point number to an arbitrary number of decimals. @@ -7105,12 +7177,12 @@ The returned value is the same type of :ref:`Variant` as ``step`` snapped(100, 32) # Returns 96 snapped(3.14159, 0.01) # Returns 3.14 - + snapped(Vector2(34, 70), Vector2(8, 8)) # Returns (32, 72) -See also :ref:`ceil`, :ref:`floor`, and :ref:`round`. +See also :ref:`ceil()`, :ref:`floor()`, and :ref:`round()`. -\ **Note:** For better type safety, use :ref:`snappedf`, :ref:`snappedi`, :ref:`Vector2.snapped`, :ref:`Vector2i.snapped`, :ref:`Vector3.snapped`, :ref:`Vector3i.snapped`, :ref:`Vector4.snapped`, or :ref:`Vector4i.snapped`. +\ **Note:** For better type safety, use :ref:`snappedf()`, :ref:`snappedi()`, :ref:`Vector2.snapped()`, :ref:`Vector2i.snapped()`, :ref:`Vector3.snapped()`, :ref:`Vector3i.snapped()`, :ref:`Vector4.snapped()`, or :ref:`Vector4i.snapped()`. .. rst-class:: classref-item-separator @@ -7120,11 +7192,11 @@ See also :ref:`ceil`, :ref:`floor` **snappedf**\ (\ x\: :ref:`float`, step\: :ref:`float`\ ) +:ref:`float` **snappedf**\ (\ x\: :ref:`float`, step\: :ref:`float`\ ) :ref:`🔗` Returns the multiple of ``step`` that is the closest to ``x``. This can also be used to round a floating-point number to an arbitrary number of decimals. -A type-safe version of :ref:`snapped`, returning a :ref:`float`. +A type-safe version of :ref:`snapped()`, returning a :ref:`float`. :: @@ -7139,11 +7211,11 @@ A type-safe version of :ref:`snapped`, return .. rst-class:: classref-method -:ref:`int` **snappedi**\ (\ x\: :ref:`float`, step\: :ref:`int`\ ) +:ref:`int` **snappedi**\ (\ x\: :ref:`float`, step\: :ref:`int`\ ) :ref:`🔗` Returns the multiple of ``step`` that is the closest to ``x``. -A type-safe version of :ref:`snapped`, returning an :ref:`int`. +A type-safe version of :ref:`snapped()`, returning an :ref:`int`. :: @@ -7158,7 +7230,7 @@ A type-safe version of :ref:`snapped`, return .. rst-class:: classref-method -:ref:`float` **sqrt**\ (\ x\: :ref:`float`\ ) +:ref:`float` **sqrt**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the square root of ``x``, where ``x`` is a non-negative number. @@ -7168,7 +7240,7 @@ Returns the square root of ``x``, where ``x`` is a non-negative number. sqrt(10.24) # Returns 3.2 sqrt(-1) # Returns NaN -\ **Note:** Negative values of ``x`` return NaN ("Not a Number"). in C#, if you need negative inputs, use ``System.Numerics.Complex``. +\ **Note:** Negative values of ``x`` return NaN ("Not a Number"). In C#, if you need negative inputs, use ``System.Numerics.Complex``. .. rst-class:: classref-item-separator @@ -7178,7 +7250,7 @@ Returns the square root of ``x``, where ``x`` is a non-negative number. .. rst-class:: classref-method -:ref:`int` **step_decimals**\ (\ x\: :ref:`float`\ ) +:ref:`int` **step_decimals**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the position of the first non-zero digit, after the decimal point. Note that the maximum return value is 10, which is a design decision in the implementation. @@ -7196,7 +7268,7 @@ Returns the position of the first non-zero digit, after the decimal point. Note .. rst-class:: classref-method -:ref:`String` **str**\ (\ ...\ ) |vararg| +:ref:`String` **str**\ (\ ...\ ) |vararg| :ref:`🔗` Converts one or more arguments of any :ref:`Variant` type to a :ref:`String` in the best way possible. @@ -7215,9 +7287,9 @@ Converts one or more arguments of any :ref:`Variant` type to a :r .. rst-class:: classref-method -:ref:`Variant` **str_to_var**\ (\ string\: :ref:`String`\ ) +:ref:`Variant` **str_to_var**\ (\ string\: :ref:`String`\ ) :ref:`🔗` -Converts a formatted ``string`` that was returned by :ref:`var_to_str` to the original :ref:`Variant`. +Converts a formatted ``string`` that was returned by :ref:`var_to_str()` to the original :ref:`Variant`. .. tabs:: @@ -7244,7 +7316,7 @@ Converts a formatted ``string`` that was returned by :ref:`var_to_str` **tan**\ (\ angle_rad\: :ref:`float`\ ) +:ref:`float` **tan**\ (\ angle_rad\: :ref:`float`\ ) :ref:`🔗` Returns the tangent of angle ``angle_rad`` in radians. @@ -7260,7 +7332,7 @@ Returns the tangent of angle ``angle_rad`` in radians. .. rst-class:: classref-method -:ref:`float` **tanh**\ (\ x\: :ref:`float`\ ) +:ref:`float` **tanh**\ (\ x\: :ref:`float`\ ) :ref:`🔗` Returns the hyperbolic tangent of ``x``. @@ -7277,7 +7349,7 @@ Returns the hyperbolic tangent of ``x``. .. rst-class:: classref-method -:ref:`Variant` **type_convert**\ (\ variant\: :ref:`Variant`, type\: :ref:`int`\ ) +:ref:`Variant` **type_convert**\ (\ variant\: :ref:`Variant`, type\: :ref:`int`\ ) :ref:`🔗` Converts the given ``variant`` to the given ``type``, using the :ref:`Variant.Type` values. This method is generous with how it handles types, it can automatically convert between array types, convert numeric :ref:`String`\ s to :ref:`int`, and converting most things to :ref:`String`. @@ -7301,17 +7373,17 @@ The returned value is a :ref:`Variant`, but the data inside and i .. rst-class:: classref-method -:ref:`String` **type_string**\ (\ type\: :ref:`int`\ ) +:ref:`String` **type_string**\ (\ type\: :ref:`int`\ ) :ref:`🔗` Returns a human-readable name of the given ``type``, using the :ref:`Variant.Type` values. :: - print(TYPE_INT) # Prints 2. - print(type_string(TYPE_INT)) # Prints "int". - print(type_string(TYPE_STRING)) # Prints "String". + print(TYPE_INT) # Prints 2 + print(type_string(TYPE_INT)) # Prints "int" + print(type_string(TYPE_STRING)) # Prints "String" -See also :ref:`typeof`. +See also :ref:`typeof()`. .. rst-class:: classref-item-separator @@ -7321,7 +7393,7 @@ See also :ref:`typeof`. .. rst-class:: classref-method -:ref:`int` **typeof**\ (\ variable\: :ref:`Variant`\ ) +:ref:`int` **typeof**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` Returns the internal type of the given ``variable``, using the :ref:`Variant.Type` values. @@ -7330,12 +7402,12 @@ Returns the internal type of the given ``variable``, using the :ref:`Variant.Typ var json = JSON.new() json.parse('["a", "b", "c"]') var result = json.get_data() - if typeof(result) == TYPE_ARRAY: - print(result[0]) # Prints a + if result is Array: + print(result[0]) # Prints "a" else: - print("Unexpected result") + print("Unexpected result!") -See also :ref:`type_string`. +See also :ref:`type_string()`. .. rst-class:: classref-item-separator @@ -7345,11 +7417,11 @@ See also :ref:`type_string`. .. rst-class:: classref-method -:ref:`PackedByteArray` **var_to_bytes**\ (\ variable\: :ref:`Variant`\ ) +:ref:`PackedByteArray` **var_to_bytes**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` -Encodes a :ref:`Variant` value to a byte array, without encoding objects. Deserialization can be done with :ref:`bytes_to_var`. +Encodes a :ref:`Variant` value to a byte array, without encoding objects. Deserialization can be done with :ref:`bytes_to_var()`. -\ **Note:** If you need object serialization, see :ref:`var_to_bytes_with_objects`. +\ **Note:** If you need object serialization, see :ref:`var_to_bytes_with_objects()`. \ **Note:** Encoding :ref:`Callable` is not supported and will result in an empty value, regardless of the data. @@ -7361,9 +7433,9 @@ Encodes a :ref:`Variant` value to a byte array, without encoding .. rst-class:: classref-method -:ref:`PackedByteArray` **var_to_bytes_with_objects**\ (\ variable\: :ref:`Variant`\ ) +:ref:`PackedByteArray` **var_to_bytes_with_objects**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` -Encodes a :ref:`Variant` value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with :ref:`bytes_to_var_with_objects`. +Encodes a :ref:`Variant` value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with :ref:`bytes_to_var_with_objects()`. \ **Note:** Encoding :ref:`Callable` is not supported and will result in an empty value, regardless of the data. @@ -7375,9 +7447,9 @@ Encodes a :ref:`Variant` value to a byte array. Encoding objects .. rst-class:: classref-method -:ref:`String` **var_to_str**\ (\ variable\: :ref:`Variant`\ ) +:ref:`String` **var_to_str**\ (\ variable\: :ref:`Variant`\ ) :ref:`🔗` -Converts a :ref:`Variant` ``variable`` to a formatted :ref:`String` that can then be parsed using :ref:`str_to_var`. +Converts a :ref:`Variant` ``variable`` to a formatted :ref:`String` that can then be parsed using :ref:`str_to_var()`. .. tabs:: @@ -7396,7 +7468,7 @@ Converts a :ref:`Variant` ``variable`` to a formatted :ref:`Strin Prints: -:: +.. code:: text { "a": 1, @@ -7413,7 +7485,7 @@ Prints: .. rst-class:: classref-method -:ref:`Variant` **weakref**\ (\ obj\: :ref:`Variant`\ ) +:ref:`Variant` **weakref**\ (\ obj\: :ref:`Variant`\ ) :ref:`🔗` Returns a :ref:`WeakRef` instance holding a weak reference to ``obj``. Returns an empty :ref:`WeakRef` instance if ``obj`` is ``null``. Prints an error and returns ``null`` if ``obj`` is neither :ref:`Object`-derived nor ``null``. @@ -7427,20 +7499,20 @@ A weak reference to an object is not enough to keep the object alive: when the o .. rst-class:: classref-method -:ref:`Variant` **wrap**\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) +:ref:`Variant` **wrap**\ (\ value\: :ref:`Variant`, min\: :ref:`Variant`, max\: :ref:`Variant`\ ) :ref:`🔗` -Wraps the :ref:`Variant` ``value`` between ``min`` and ``max``. Can be used for creating loop-alike behavior or infinite surfaces. +Wraps the :ref:`Variant` ``value`` between ``min`` and ``max``. ``min`` is *inclusive* while ``max`` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. -Variant types :ref:`int` and :ref:`float` are supported. If any of the arguments is :ref:`float` this function returns a :ref:`float`, otherwise it returns an :ref:`int`. +Variant types :ref:`int` and :ref:`float` are supported. If any of the arguments is :ref:`float`, this function returns a :ref:`float`, otherwise it returns an :ref:`int`. :: var a = wrap(4, 5, 10) # a is 9 (int) - + var a = wrap(7, 5, 10) # a is 7 (int) - + var a = wrap(10.5, 5, 10) # a is 5.5 (float) @@ -7452,9 +7524,9 @@ Variant types :ref:`int` and :ref:`float` are supported. .. rst-class:: classref-method -:ref:`float` **wrapf**\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) +:ref:`float` **wrapf**\ (\ value\: :ref:`float`, min\: :ref:`float`, max\: :ref:`float`\ ) :ref:`🔗` -Wraps the float ``value`` between ``min`` and ``max``. Can be used for creating loop-alike behavior or infinite surfaces. +Wraps the float ``value`` between ``min`` and ``max``. ``min`` is *inclusive* while ``max`` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. :: @@ -7471,9 +7543,7 @@ Wraps the float ``value`` between ``min`` and ``max``. Can be used for creating # Infinite rotation (in radians) angle = wrapf(angle + 0.1, -PI, PI) -\ **Note:** If ``min`` is ``0``, this is equivalent to :ref:`fposmod`, so prefer using that instead. - -\ :ref:`wrapf` is more flexible than using the :ref:`fposmod` approach by giving the user control over the minimum value. +\ **Note:** If ``min`` is ``0``, this is equivalent to :ref:`fposmod()`, so prefer using that instead. :ref:`wrapf()` is more flexible than using the :ref:`fposmod()` approach by giving the user control over the minimum value. .. rst-class:: classref-item-separator @@ -7483,9 +7553,9 @@ Wraps the float ``value`` between ``min`` and ``max``. Can be used for creating .. rst-class:: classref-method -:ref:`int` **wrapi**\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) +:ref:`int` **wrapi**\ (\ value\: :ref:`int`, min\: :ref:`int`, max\: :ref:`int`\ ) :ref:`🔗` -Wraps the integer ``value`` between ``min`` and ``max``. Can be used for creating loop-alike behavior or infinite surfaces. +Wraps the integer ``value`` between ``min`` and ``max``. ``min`` is *inclusive* while ``max`` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. :: @@ -7498,6 +7568,7 @@ Wraps the integer ``value`` between ``min`` and ``max``. Can be used for creatin var result = wrapi(-6, -5, -1) .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 804c80004c8..e07be295a85 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -17,13 +17,13 @@ A 3D axis-aligned bounding box. Description ----------- -The **AABB** built-in :ref:`Variant` type represents an axis-aligned bounding box in a 3D space. It is defined by its :ref:`position` and :ref:`size`, which are :ref:`Vector3`. It is frequently used for fast overlap tests (see :ref:`intersects`). Although **AABB** itself is axis-aligned, it can be combined with :ref:`Transform3D` to represent a rotated or skewed bounding box. +The **AABB** built-in :ref:`Variant` type represents an axis-aligned bounding box in a 3D space. It is defined by its :ref:`position` and :ref:`size`, which are :ref:`Vector3`. It is frequently used for fast overlap tests (see :ref:`intersects()`). Although **AABB** itself is axis-aligned, it can be combined with :ref:`Transform3D` to represent a rotated or skewed bounding box. It uses floating-point coordinates. The 2D counterpart to **AABB** is :ref:`Rect2`. There is no version of **AABB** that uses integer coordinates. -\ **Note:** Negative values for :ref:`size` are not supported. With negative size, most **AABB** methods do not work correctly. Use :ref:`abs` to get an equivalent **AABB** with a non-negative size. +\ **Note:** Negative values for :ref:`size` are not supported. With negative size, most **AABB** methods do not work correctly. Use :ref:`abs()` to get an equivalent **AABB** with a non-negative size. -\ **Note:** In a boolean context, a **AABB** evaluates to ``false`` if both :ref:`position` and :ref:`size` are zero (equal to :ref:`Vector3.ZERO`). Otherwise, it always evaluates to ``true``. +\ **Note:** In a boolean context, an **AABB** evaluates to ``false`` if both :ref:`position` and :ref:`size` are zero (equal to :ref:`Vector3.ZERO`). Otherwise, it always evaluates to ``true``. .. note:: @@ -103,7 +103,7 @@ Methods +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_shortest_axis_size`\ (\ ) |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector3` | :ref:`get_support`\ (\ dir\: :ref:`Vector3`\ ) |const| | + | :ref:`Vector3` | :ref:`get_support`\ (\ direction\: :ref:`Vector3`\ ) |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_volume`\ (\ ) |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -161,9 +161,9 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Vector3` **end** = ``Vector3(0, 0, 0)`` +:ref:`Vector3` **end** = ``Vector3(0, 0, 0)`` :ref:`🔗` -The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to ``position + size``. Setting this point affects the :ref:`size`. +The ending point. This is usually the corner on the top-right and back of the bounding box, and is equivalent to ``position + size``. Setting this point affects the :ref:`size`. .. rst-class:: classref-item-separator @@ -173,9 +173,9 @@ The ending point. This is usually the corner on the top-right and forward of the .. rst-class:: classref-property -:ref:`Vector3` **position** = ``Vector3(0, 0, 0)`` +:ref:`Vector3` **position** = ``Vector3(0, 0, 0)`` :ref:`🔗` -The origin point. This is usually the corner on the bottom-left and back of the bounding box. +The origin point. This is usually the corner on the bottom-left and forward of the bounding box. .. rst-class:: classref-item-separator @@ -185,11 +185,11 @@ The origin point. This is usually the corner on the bottom-left and back of the .. rst-class:: classref-property -:ref:`Vector3` **size** = ``Vector3(0, 0, 0)`` +:ref:`Vector3` **size** = ``Vector3(0, 0, 0)`` :ref:`🔗` The bounding box's width, height, and depth starting from :ref:`position`. Setting this value also affects the :ref:`end` point. -\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the :ref:`position` is the bottom-left-back corner, and the :ref:`end` is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use :ref:`abs`. +\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the :ref:`position` is the bottom-left-forward corner, and the :ref:`end` is the top-right-back corner. To get an equivalent bounding box with non-negative size, use :ref:`abs()`. .. rst-class:: classref-section-separator @@ -204,7 +204,7 @@ Constructor Descriptions .. rst-class:: classref-constructor -:ref:`AABB` **AABB**\ (\ ) +:ref:`AABB` **AABB**\ (\ ) :ref:`🔗` Constructs an **AABB** with its :ref:`position` and :ref:`size` set to :ref:`Vector3.ZERO`. @@ -241,7 +241,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`AABB` **abs**\ (\ ) |const| +:ref:`AABB` **abs**\ (\ ) |const| :ref:`🔗` Returns an **AABB** equivalent to this bounding box, with its width, height, and depth modified to be non-negative values. @@ -252,8 +252,8 @@ Returns an **AABB** equivalent to this bounding box, with its width, height, and var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5)) var absolute = box.abs() - print(absolute.position) # Prints (-15, -10, 0) - print(absolute.size) # Prints (20, 10, 5) + print(absolute.position) # Prints (-15.0, -10.0, 0.0) + print(absolute.size) # Prints (20.0, 10.0, 5.0) .. code-tab:: csharp @@ -274,7 +274,7 @@ Returns an **AABB** equivalent to this bounding box, with its width, height, and .. rst-class:: classref-method -:ref:`bool` **encloses**\ (\ with\: :ref:`AABB`\ ) |const| +:ref:`bool` **encloses**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` Returns ``true`` if this bounding box *completely* encloses the ``with`` box. The edges of both boxes are included. @@ -286,7 +286,7 @@ Returns ``true`` if this bounding box *completely* encloses the ``with`` box. Th var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4)) var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3)) var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8)) - + print(a.encloses(a)) # Prints true print(a.encloses(b)) # Prints true print(a.encloses(c)) # Prints false @@ -296,7 +296,7 @@ Returns ``true`` if this bounding box *completely* encloses the ``with`` box. Th var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4)); var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3)); var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8)); - + GD.Print(a.Encloses(a)); // Prints True GD.Print(a.Encloses(b)); // Prints True GD.Print(a.Encloses(c)); // Prints False @@ -311,7 +311,7 @@ Returns ``true`` if this bounding box *completely* encloses the ``with`` box. Th .. rst-class:: classref-method -:ref:`AABB` **expand**\ (\ to_point\: :ref:`Vector3`\ ) |const| +:ref:`AABB` **expand**\ (\ to_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns a copy of this bounding box expanded to align the edges with the given ``to_point``, if necessary. @@ -321,23 +321,23 @@ Returns a copy of this bounding box expanded to align the edges with the given ` .. code-tab:: gdscript var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5)) - + box = box.expand(Vector3(10, 0, 0)) - print(box.position) # Prints (0, 0, 0) - print(box.size) # Prints (10, 2, 5) - + print(box.position) # Prints (0.0, 0.0, 0.0) + print(box.size) # Prints (10.0, 2.0, 5.0) + box = box.expand(Vector3(-5, 0, 5)) - print(box.position) # Prints (-5, 0, 0) - print(box.size) # Prints (15, 2, 5) + print(box.position) # Prints (-5.0, 0.0, 0.0) + print(box.size) # Prints (15.0, 2.0, 5.0) .. code-tab:: csharp var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5)); - + box = box.Expand(new Vector3(10, 0, 0)); GD.Print(box.Position); // Prints (0, 0, 0) GD.Print(box.Size); // Prints (10, 2, 5) - + box = box.Expand(new Vector3(-5, 0, 5)); GD.Print(box.Position); // Prints (-5, 0, 0) GD.Print(box.Size); // Prints (15, 2, 5) @@ -352,7 +352,7 @@ Returns a copy of this bounding box expanded to align the edges with the given ` .. rst-class:: classref-method -:ref:`Vector3` **get_center**\ (\ ) |const| +:ref:`Vector3` **get_center**\ (\ ) |const| :ref:`🔗` Returns the center point of the bounding box. This is the same as ``position + (size / 2.0)``. @@ -364,9 +364,9 @@ Returns the center point of the bounding box. This is the same as ``position + ( .. rst-class:: classref-method -:ref:`Vector3` **get_endpoint**\ (\ idx\: :ref:`int`\ ) |const| +:ref:`Vector3` **get_endpoint**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the position of one of the 8 vertices that compose this bounding box. With a ``idx`` of ``0`` this is the same as :ref:`position`, and a ``idx`` of ``7`` is the same as :ref:`end`. +Returns the position of one of the 8 vertices that compose this bounding box. With an ``idx`` of ``0`` this is the same as :ref:`position`, and an ``idx`` of ``7`` is the same as :ref:`end`. .. rst-class:: classref-item-separator @@ -376,7 +376,7 @@ Returns the position of one of the 8 vertices that compose this bounding box. Wi .. rst-class:: classref-method -:ref:`Vector3` **get_longest_axis**\ (\ ) |const| +:ref:`Vector3` **get_longest_axis**\ (\ ) |const| :ref:`🔗` Returns the longest normalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). @@ -386,22 +386,22 @@ Returns the longest normalized axis of this bounding box's :ref:`size` and :ref:`get_longest_axis_size`. +See also :ref:`get_longest_axis_index()` and :ref:`get_longest_axis_size()`. .. rst-class:: classref-item-separator @@ -411,11 +411,11 @@ See also :ref:`get_longest_axis_index` .. rst-class:: classref-method -:ref:`int` **get_longest_axis_index**\ (\ ) |const| +:ref:`int` **get_longest_axis_index**\ (\ ) |const| :ref:`🔗` Returns the index to the longest axis of this bounding box's :ref:`size` (see :ref:`Vector3.AXIS_X`, :ref:`Vector3.AXIS_Y`, and :ref:`Vector3.AXIS_Z`). -For an example, see :ref:`get_longest_axis`. +For an example, see :ref:`get_longest_axis()`. .. rst-class:: classref-item-separator @@ -425,11 +425,11 @@ For an example, see :ref:`get_longest_axis`. .. rst-class:: classref-method -:ref:`float` **get_longest_axis_size**\ (\ ) |const| +:ref:`float` **get_longest_axis_size**\ (\ ) |const| :ref:`🔗` Returns the longest dimension of this bounding box's :ref:`size`. -For an example, see :ref:`get_longest_axis`. +For an example, see :ref:`get_longest_axis()`. .. rst-class:: classref-item-separator @@ -439,9 +439,9 @@ For an example, see :ref:`get_longest_axis`. .. rst-class:: classref-method -:ref:`Vector3` **get_shortest_axis**\ (\ ) |const| +:ref:`Vector3` **get_shortest_axis**\ (\ ) |const| :ref:`🔗` -Returns the shortest normaalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). +Returns the shortest normalized axis of this bounding box's :ref:`size`, as a :ref:`Vector3` (:ref:`Vector3.RIGHT`, :ref:`Vector3.UP`, or :ref:`Vector3.BACK`). .. tabs:: @@ -449,22 +449,22 @@ Returns the shortest normaalized axis of this bounding box's :ref:`size` and :ref:`get_shortest_axis_size`. +See also :ref:`get_shortest_axis_index()` and :ref:`get_shortest_axis_size()`. .. rst-class:: classref-item-separator @@ -474,11 +474,11 @@ See also :ref:`get_shortest_axis_index` **get_shortest_axis_index**\ (\ ) |const| +:ref:`int` **get_shortest_axis_index**\ (\ ) |const| :ref:`🔗` Returns the index to the shortest axis of this bounding box's :ref:`size` (see :ref:`Vector3.AXIS_X`, :ref:`Vector3.AXIS_Y`, and :ref:`Vector3.AXIS_Z`). -For an example, see :ref:`get_shortest_axis`. +For an example, see :ref:`get_shortest_axis()`. .. rst-class:: classref-item-separator @@ -488,11 +488,11 @@ For an example, see :ref:`get_shortest_axis .. rst-class:: classref-method -:ref:`float` **get_shortest_axis_size**\ (\ ) |const| +:ref:`float` **get_shortest_axis_size**\ (\ ) |const| :ref:`🔗` Returns the shortest dimension of this bounding box's :ref:`size`. -For an example, see :ref:`get_shortest_axis`. +For an example, see :ref:`get_shortest_axis()`. .. rst-class:: classref-item-separator @@ -502,7 +502,7 @@ For an example, see :ref:`get_shortest_axis .. rst-class:: classref-method -:ref:`Vector3` **get_support**\ (\ dir\: :ref:`Vector3`\ ) |const| +:ref:`Vector3` **get_support**\ (\ direction\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the vertex's position of this bounding box that's the farthest in the given direction. This point is commonly known as the support point in collision detection algorithms. @@ -514,9 +514,9 @@ Returns the vertex's position of this bounding box that's the farthest in the gi .. rst-class:: classref-method -:ref:`float` **get_volume**\ (\ ) |const| +:ref:`float` **get_volume**\ (\ ) |const| :ref:`🔗` -Returns the bounding box's volume. This is equivalent to ``size.x * size.y * size.z``. See also :ref:`has_volume`. +Returns the bounding box's volume. This is equivalent to ``size.x * size.y * size.z``. See also :ref:`has_volume()`. .. rst-class:: classref-item-separator @@ -526,7 +526,7 @@ Returns the bounding box's volume. This is equivalent to ``size.x * size.y * siz .. rst-class:: classref-method -:ref:`AABB` **grow**\ (\ by\: :ref:`float`\ ) |const| +:ref:`AABB` **grow**\ (\ by\: :ref:`float`\ ) |const| :ref:`🔗` Returns a copy of this bounding box extended on all sides by the given amount ``by``. A negative amount shrinks the box instead. @@ -536,19 +536,19 @@ Returns a copy of this bounding box extended on all sides by the given amount `` .. code-tab:: gdscript var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4) - print(a.position) # Prints (0, 0, 0) - print(a.size) # Prints (16, 16, 16) - + print(a.position) # Prints (0.0, 0.0, 0.0) + print(a.size) # Prints (16.0, 16.0, 16.0) + var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2) - print(b.position) # Prints (-2, -2, -2) - print(b.size) # Prints (12, 8, 6) + print(b.position) # Prints (-2.0, -2.0, -2.0) + print(b.size) # Prints (12.0, 8.0, 6.0) .. code-tab:: csharp var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4); GD.Print(a.Position); // Prints (0, 0, 0) GD.Print(a.Size); // Prints (16, 16, 16) - + var b = new Aabb(new Vector3(0, 0, 0), new Vector3(8, 4, 2)).Grow(2); GD.Print(b.Position); // Prints (-2, -2, -2) GD.Print(b.Size); // Prints (12, 8, 6) @@ -563,11 +563,11 @@ Returns a copy of this bounding box extended on all sides by the given amount `` .. rst-class:: classref-method -:ref:`bool` **has_point**\ (\ point\: :ref:`Vector3`\ ) |const| +:ref:`bool` **has_point**\ (\ point\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns ``true`` if the bounding box contains the given ``point``. By convention, points exactly on the right, top, and front sides are **not** included. -\ **Note:** This method is not reliable for **AABB** with a *negative* :ref:`size`. Use :ref:`abs` first to get a valid bounding box. +\ **Note:** This method is not reliable for **AABB** with a *negative* :ref:`size`. Use :ref:`abs()` first to get a valid bounding box. .. rst-class:: classref-item-separator @@ -577,7 +577,7 @@ Returns ``true`` if the bounding box contains the given ``point``. By convention .. rst-class:: classref-method -:ref:`bool` **has_surface**\ (\ ) |const| +:ref:`bool` **has_surface**\ (\ ) |const| :ref:`🔗` Returns ``true`` if this bounding box has a surface or a length, that is, at least one component of :ref:`size` is greater than ``0``. Otherwise, returns ``false``. @@ -589,9 +589,9 @@ Returns ``true`` if this bounding box has a surface or a length, that is, at lea .. rst-class:: classref-method -:ref:`bool` **has_volume**\ (\ ) |const| +:ref:`bool` **has_volume**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if this bounding box's width, height, and depth are all positive. See also :ref:`get_volume`. +Returns ``true`` if this bounding box's width, height, and depth are all positive. See also :ref:`get_volume()`. .. rst-class:: classref-item-separator @@ -601,9 +601,9 @@ Returns ``true`` if this bounding box's width, height, and depth are all positiv .. rst-class:: classref-method -:ref:`AABB` **intersection**\ (\ with\: :ref:`AABB`\ ) |const| +:ref:`AABB` **intersection**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` -Returns the intersection between this bounding box and ``with``. If the boxes do not intersect, returns an empty **AABB**. If the boxes intersect at the edge, returns a flat **AABB** with no volume (see :ref:`has_surface` and :ref:`has_volume`). +Returns the intersection between this bounding box and ``with``. If the boxes do not intersect, returns an empty **AABB**. If the boxes intersect at the edge, returns a flat **AABB** with no volume (see :ref:`has_surface()` and :ref:`has_volume()`). .. tabs:: @@ -612,23 +612,23 @@ Returns the intersection between this bounding box and ``with``. If the boxes do var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8)) var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4)) - + var intersection = box1.intersection(box2) - print(intersection.position) # Prints (2, 0, 2) - print(intersection.size) # Prints (3, 2, 4) + print(intersection.position) # Prints (2.0, 0.0, 2.0) + print(intersection.size) # Prints (3.0, 2.0, 4.0) .. code-tab:: csharp var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8)); var box2 = new Aabb(new Vector3(2, 0, 2), new Vector3(8, 4, 4)); - + var intersection = box1.Intersection(box2); GD.Print(intersection.Position); // Prints (2, 0, 2) GD.Print(intersection.Size); // Prints (3, 2, 4) -\ **Note:** If you only need to know whether two bounding boxes are intersecting, use :ref:`intersects`, instead. +\ **Note:** If you only need to know whether two bounding boxes are intersecting, use :ref:`intersects()`, instead. .. rst-class:: classref-item-separator @@ -638,7 +638,7 @@ Returns the intersection between this bounding box and ``with``. If the boxes do .. rst-class:: classref-method -:ref:`bool` **intersects**\ (\ with\: :ref:`AABB`\ ) |const| +:ref:`bool` **intersects**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` Returns ``true`` if this bounding box overlaps with the box ``with``. The edges of both boxes are *always* excluded. @@ -650,7 +650,7 @@ Returns ``true`` if this bounding box overlaps with the box ``with``. The edges .. rst-class:: classref-method -:ref:`bool` **intersects_plane**\ (\ plane\: :ref:`Plane`\ ) |const| +:ref:`bool` **intersects_plane**\ (\ plane\: :ref:`Plane`\ ) |const| :ref:`🔗` Returns ``true`` if this bounding box is on both sides of the given ``plane``. @@ -662,7 +662,7 @@ Returns ``true`` if this bounding box is on both sides of the given ``plane``. .. rst-class:: classref-method -:ref:`Variant` **intersects_ray**\ (\ from\: :ref:`Vector3`, dir\: :ref:`Vector3`\ ) |const| +:ref:`Variant` **intersects_ray**\ (\ from\: :ref:`Vector3`, dir\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the first point where this bounding box and the given ray intersect, as a :ref:`Vector3`. If no intersection occurs, returns ``null``. @@ -676,7 +676,7 @@ The ray begin at ``from``, faces ``dir`` and extends towards infinity. .. rst-class:: classref-method -:ref:`Variant` **intersects_segment**\ (\ from\: :ref:`Vector3`, to\: :ref:`Vector3`\ ) |const| +:ref:`Variant` **intersects_segment**\ (\ from\: :ref:`Vector3`, to\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the first point where this bounding box and the given segment intersect, as a :ref:`Vector3`. If no intersection occurs, returns ``null``. @@ -690,9 +690,9 @@ The segment begins at ``from`` and ends at ``to``. .. rst-class:: classref-method -:ref:`bool` **is_equal_approx**\ (\ aabb\: :ref:`AABB`\ ) |const| +:ref:`bool` **is_equal_approx**\ (\ aabb\: :ref:`AABB`\ ) |const| :ref:`🔗` -Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by calling :ref:`Vector2.is_equal_approx` on the :ref:`position` and the :ref:`size`. +Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by calling :ref:`Vector3.is_equal_approx()` on the :ref:`position` and the :ref:`size`. .. rst-class:: classref-item-separator @@ -702,9 +702,9 @@ Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by c .. rst-class:: classref-method -:ref:`bool` **is_finite**\ (\ ) |const| +:ref:`bool` **is_finite**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if this bounding box's values are finite, by calling :ref:`Vector2.is_finite` on the :ref:`position` and the :ref:`size`. +Returns ``true`` if this bounding box's values are finite, by calling :ref:`Vector3.is_finite()` on the :ref:`position` and the :ref:`size`. .. rst-class:: classref-item-separator @@ -714,9 +714,9 @@ Returns ``true`` if this bounding box's values are finite, by calling :ref:`Vect .. rst-class:: classref-method -:ref:`AABB` **merge**\ (\ with\: :ref:`AABB`\ ) |const| +:ref:`AABB` **merge**\ (\ with\: :ref:`AABB`\ ) |const| :ref:`🔗` -Returns an **AABB** that encloses both this bounding box and ``with`` around the edges. See also :ref:`encloses`. +Returns an **AABB** that encloses both this bounding box and ``with`` around the edges. See also :ref:`encloses()`. .. rst-class:: classref-section-separator @@ -731,11 +731,11 @@ Operator Descriptions .. rst-class:: classref-operator -:ref:`bool` **operator !=**\ (\ right\: :ref:`AABB`\ ) +:ref:`bool` **operator !=**\ (\ right\: :ref:`AABB`\ ) :ref:`🔗` Returns ``true`` if the :ref:`position` or :ref:`size` of both bounding boxes are not equal. -\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. .. rst-class:: classref-item-separator @@ -745,13 +745,13 @@ Returns ``true`` if the :ref:`position` or :ref:`s .. rst-class:: classref-operator -:ref:`AABB` **operator ***\ (\ right\: :ref:`Transform3D`\ ) +:ref:`AABB` **operator ***\ (\ right\: :ref:`Transform3D`\ ) :ref:`🔗` Inversely transforms (multiplies) the **AABB** by the given :ref:`Transform3D` transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). -\ ``aabb * transform`` is equivalent to ``transform.inverse() * aabb``. See :ref:`Transform3D.inverse`. +\ ``aabb * transform`` is equivalent to ``transform.inverse() * aabb``. See :ref:`Transform3D.inverse()`. -For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * aabb`` can be used instead. See :ref:`Transform3D.affine_inverse`. +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * aabb`` can be used instead. See :ref:`Transform3D.affine_inverse()`. .. rst-class:: classref-item-separator @@ -761,13 +761,14 @@ For transforming by inverse of an affine transformation (e.g. with scaling) ``tr .. rst-class:: classref-operator -:ref:`bool` **operator ==**\ (\ right\: :ref:`AABB`\ ) +:ref:`bool` **operator ==**\ (\ right\: :ref:`AABB`\ ) :ref:`🔗` Returns ``true`` if both :ref:`position` and :ref:`size` of the bounding boxes are exactly equal, respectively. -\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_acceptdialog.rst b/classes/class_acceptdialog.rst index a3c3bf190af..0d02fdb51e6 100644 --- a/classes/class_acceptdialog.rst +++ b/classes/class_acceptdialog.rst @@ -21,7 +21,7 @@ A base dialog used for user notification. Description ----------- -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. +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 @@ -44,7 +44,11 @@ Properties +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ | :ref:`bool` | keep_title_visible | ``true`` (overrides :ref:`Window`) | +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ - | :ref:`String` | :ref:`ok_button_text` | ``"OK"`` | + | :ref:`bool` | maximize_disabled | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`bool` | minimize_disabled | ``true`` (overrides :ref:`Window`) | + +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`ok_button_text` | ``""`` | +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ | :ref:`String` | title | ``"Alert!"`` (overrides :ref:`Window`) | +-----------------------------+-----------------------------------------------------------------------------------+------------------------------------------------------------------------------+ @@ -72,9 +76,9 @@ Methods +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Button` | :ref:`get_ok_button`\ (\ ) | +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`register_text_enter`\ (\ line_edit\: :ref:`Control`\ ) | + | |void| | :ref:`register_text_enter`\ (\ line_edit\: :ref:`LineEdit`\ ) | +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`remove_button`\ (\ button\: :ref:`Control`\ ) | + | |void| | :ref:`remove_button`\ (\ button\: :ref:`Button`\ ) | +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -85,6 +89,10 @@ Theme Properties .. table:: :widths: auto + +---------------------------------+---------------------------------------------------------------------------------+--------+ + | :ref:`int` | :ref:`buttons_min_height` | ``0`` | + +---------------------------------+---------------------------------------------------------------------------------+--------+ + | :ref:`int` | :ref:`buttons_min_width` | ``0`` | +---------------------------------+---------------------------------------------------------------------------------+--------+ | :ref:`int` | :ref:`buttons_separation` | ``10`` | +---------------------------------+---------------------------------------------------------------------------------+--------+ @@ -104,9 +112,9 @@ Signals .. rst-class:: classref-signal -**canceled**\ (\ ) +**canceled**\ (\ ) :ref:`🔗` -Emitted when the dialog is closed or the button created with :ref:`add_cancel_button` is pressed. +Emitted when the dialog is closed or the button created with :ref:`add_cancel_button()` is pressed. .. rst-class:: classref-item-separator @@ -116,7 +124,7 @@ Emitted when the dialog is closed or the button created with :ref:`add_cancel_bu .. rst-class:: classref-signal -**confirmed**\ (\ ) +**confirmed**\ (\ ) :ref:`🔗` Emitted when the dialog is accepted, i.e. the OK button is pressed. @@ -128,9 +136,9 @@ Emitted when the dialog is accepted, i.e. the OK button is pressed. .. rst-class:: classref-signal -**custom_action**\ (\ action\: :ref:`StringName`\ ) +**custom_action**\ (\ action\: :ref:`StringName`\ ) :ref:`🔗` -Emitted when a custom button is pressed. See :ref:`add_button`. +Emitted when a custom button with an action is pressed. See :ref:`add_button()`. .. rst-class:: classref-section-separator @@ -145,7 +153,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **dialog_autowrap** = ``false`` +:ref:`bool` **dialog_autowrap** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -162,14 +170,14 @@ Sets autowrapping for the text in the dialog. .. rst-class:: classref-property -:ref:`bool` **dialog_close_on_escape** = ``true`` +:ref:`bool` **dialog_close_on_escape** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_close_on_escape**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_close_on_escape**\ (\ ) -If ``true``, the dialog will be hidden when the escape key (:ref:`@GlobalScope.KEY_ESCAPE`) is pressed. +If ``true``, the dialog will be hidden when the ``ui_cancel`` action is pressed (by default, this action is bound to :ref:`@GlobalScope.KEY_ESCAPE`). .. rst-class:: classref-item-separator @@ -179,7 +187,7 @@ If ``true``, the dialog will be hidden when the escape key (:ref:`@GlobalScope.K .. rst-class:: classref-property -:ref:`bool` **dialog_hide_on_ok** = ``true`` +:ref:`bool` **dialog_hide_on_ok** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,7 +206,7 @@ If ``true``, the dialog is hidden when the OK button is pressed. You can set it .. rst-class:: classref-property -:ref:`String` **dialog_text** = ``""`` +:ref:`String` **dialog_text** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -215,14 +223,14 @@ The text displayed by the dialog. .. rst-class:: classref-property -:ref:`String` **ok_button_text** = ``"OK"`` +:ref:`String` **ok_button_text** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_ok_button_text**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_ok_button_text**\ (\ ) -The text displayed by the OK button (see :ref:`get_ok_button`). +The text displayed by the OK button (see :ref:`get_ok_button()`). If empty, a default text will be used. .. rst-class:: classref-section-separator @@ -237,13 +245,15 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Button` **add_button**\ (\ text\: :ref:`String`, right\: :ref:`bool` = false, action\: :ref:`String` = ""\ ) +:ref:`Button` **add_button**\ (\ text\: :ref:`String`, right\: :ref:`bool` = false, action\: :ref:`String` = ""\ ) :ref:`🔗` + +Adds a button with label ``text`` and a custom ``action`` to the dialog and returns the created button. -Adds a button with label ``text`` and a custom ``action`` to the dialog and returns the created button. ``action`` will be passed to the :ref:`custom_action` signal when pressed. +If ``action`` is not empty, pressing the button will emit the :ref:`custom_action` signal with the specified action string. If ``true``, ``right`` will place the button to the right of any sibling buttons. -You can use :ref:`remove_button` method to remove a button created with this method from the dialog. +You can use :ref:`remove_button()` method to remove a button created with this method from the dialog. .. rst-class:: classref-item-separator @@ -253,11 +263,11 @@ You can use :ref:`remove_button` method .. rst-class:: classref-method -:ref:`Button` **add_cancel_button**\ (\ name\: :ref:`String`\ ) +:ref:`Button` **add_cancel_button**\ (\ name\: :ref:`String`\ ) :ref:`🔗` Adds a button with label ``name`` and a cancel action to the dialog and returns the created button. -You can use :ref:`remove_button` method to remove a button created with this method from the dialog. +You can use :ref:`remove_button()` method to remove a button created with this method from the dialog. .. rst-class:: classref-item-separator @@ -267,7 +277,7 @@ You can use :ref:`remove_button` method .. rst-class:: classref-method -:ref:`Label` **get_label**\ (\ ) +:ref:`Label` **get_label**\ (\ ) :ref:`🔗` Returns the label used for built-in text. @@ -281,7 +291,7 @@ Returns the label used for built-in text. .. rst-class:: classref-method -:ref:`Button` **get_ok_button**\ (\ ) +:ref:`Button` **get_ok_button**\ (\ ) :ref:`🔗` Returns the OK :ref:`Button` instance. @@ -295,7 +305,7 @@ Returns the OK :ref:`Button` instance. .. rst-class:: classref-method -|void| **register_text_enter**\ (\ line_edit\: :ref:`Control`\ ) +|void| **register_text_enter**\ (\ line_edit\: :ref:`LineEdit`\ ) :ref:`🔗` Registers a :ref:`LineEdit` in the dialog. When the enter key is pressed, the dialog will be accepted. @@ -307,9 +317,9 @@ Registers a :ref:`LineEdit` in the dialog. When the enter key is .. rst-class:: classref-method -|void| **remove_button**\ (\ button\: :ref:`Control`\ ) +|void| **remove_button**\ (\ button\: :ref:`Button`\ ) :ref:`🔗` -Removes the ``button`` from the dialog. Does NOT free the ``button``. The ``button`` must be a :ref:`Button` added with :ref:`add_button` or :ref:`add_cancel_button` method. After removal, pressing the ``button`` will no longer emit this dialog's :ref:`custom_action` or :ref:`canceled` signals. +Removes the ``button`` from the dialog. Does NOT free the ``button``. The ``button`` must be a :ref:`Button` added with :ref:`add_button()` or :ref:`add_cancel_button()` method. After removal, pressing the ``button`` will no longer emit this dialog's :ref:`custom_action` or :ref:`canceled` signals. .. rst-class:: classref-section-separator @@ -320,11 +330,35 @@ Removes the ``button`` from the dialog. Does NOT free the ``button``. The ``butt Theme Property Descriptions --------------------------- +.. _class_AcceptDialog_theme_constant_buttons_min_height: + +.. rst-class:: classref-themeproperty + +:ref:`int` **buttons_min_height** = ``0`` :ref:`🔗` + +The minimum height of each button in the bottom row (such as OK/Cancel) in pixels. This can be increased to make buttons with short texts easier to click/tap. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AcceptDialog_theme_constant_buttons_min_width: + +.. rst-class:: classref-themeproperty + +:ref:`int` **buttons_min_width** = ``0`` :ref:`🔗` + +The minimum width of each button in the bottom row (such as OK/Cancel) in pixels. This can be increased to make buttons with short texts easier to click/tap. + +.. rst-class:: classref-item-separator + +---- + .. _class_AcceptDialog_theme_constant_buttons_separation: .. rst-class:: classref-themeproperty -:ref:`int` **buttons_separation** = ``10`` +:ref:`int` **buttons_separation** = ``10`` :ref:`🔗` The size of the vertical space between the dialog's content and the button row. @@ -336,11 +370,12 @@ The size of the vertical space between the dialog's content and the button row. .. rst-class:: classref-themeproperty -:ref:`StyleBox` **panel** +:ref:`StyleBox` **panel** :ref:`🔗` The panel that fills the background of the window. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_aescontext.rst b/classes/class_aescontext.rst index d5c0a64d5ee..49ee1e150d5 100644 --- a/classes/class_aescontext.rst +++ b/classes/class_aescontext.rst @@ -27,9 +27,9 @@ This class holds the context information required for encryption and decryption .. code-tab:: gdscript extends Node - + var aes = AESContext.new() - + func _ready(): var key = "My secret key!!!" # Key must be either 16 or 32 bytes. var data = "My secret text!!" # Data size must be multiple of 16 bytes, apply padding if needed. @@ -43,7 +43,7 @@ This class holds the context information required for encryption and decryption aes.finish() # Check ECB assert(decrypted == data.to_utf8_buffer()) - + var iv = "My secret iv!!!!" # IV must be of exactly 16 bytes. # Encrypt CBC aes.start(AESContext.MODE_CBC_ENCRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer()) @@ -60,11 +60,11 @@ This class holds the context information required for encryption and decryption using Godot; using System.Diagnostics; - + public partial class MyNode : Node { private AesContext _aes = new AesContext(); - + public override void _Ready() { string key = "My secret key!!!"; // Key must be either 16 or 32 bytes. @@ -79,7 +79,7 @@ This class holds the context information required for encryption and decryption _aes.Finish(); // Check ECB Debug.Assert(decrypted == data.ToUtf8Buffer()); - + string iv = "My secret iv!!!!"; // IV must be of exactly 16 bytes. // Encrypt CBC _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer()); @@ -127,7 +127,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **Mode**: +enum **Mode**: :ref:`🔗` .. _class_AESContext_constant_MODE_ECB_ENCRYPT: @@ -182,9 +182,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **finish**\ (\ ) +|void| **finish**\ (\ ) :ref:`🔗` -Close this AES context so it can be started again. See :ref:`start`. +Close this AES context so it can be started again. See :ref:`start()`. .. rst-class:: classref-item-separator @@ -194,9 +194,9 @@ Close this AES context so it can be started again. See :ref:`start` **get_iv_state**\ (\ ) +:ref:`PackedByteArray` **get_iv_state**\ (\ ) :ref:`🔗` -Get the current IV state for this context (IV gets updated when calling :ref:`update`). You normally don't need this function. +Get the current IV state for this context (IV gets updated when calling :ref:`update()`). You normally don't need this function. \ **Note:** This function only makes sense when the context is started with :ref:`MODE_CBC_ENCRYPT` or :ref:`MODE_CBC_DECRYPT`. @@ -208,7 +208,7 @@ Get the current IV state for this context (IV gets updated when calling :ref:`up .. rst-class:: classref-method -:ref:`Error` **start**\ (\ mode\: :ref:`Mode`, key\: :ref:`PackedByteArray`, iv\: :ref:`PackedByteArray` = PackedByteArray()\ ) +:ref:`Error` **start**\ (\ mode\: :ref:`Mode`, key\: :ref:`PackedByteArray`, iv\: :ref:`PackedByteArray` = PackedByteArray()\ ) :ref:`🔗` Start the AES context in the given ``mode``. A ``key`` of either 16 or 32 bytes must always be provided, while an ``iv`` (initialization vector) of exactly 16 bytes, is only needed when ``mode`` is either :ref:`MODE_CBC_ENCRYPT` or :ref:`MODE_CBC_DECRYPT`. @@ -220,13 +220,14 @@ Start the AES context in the given ``mode``. A ``key`` of either 16 or 32 bytes .. rst-class:: classref-method -:ref:`PackedByteArray` **update**\ (\ src\: :ref:`PackedByteArray`\ ) +:ref:`PackedByteArray` **update**\ (\ src\: :ref:`PackedByteArray`\ ) :ref:`🔗` -Run the desired operation for this AES context. Will return a :ref:`PackedByteArray` containing the result of encrypting (or decrypting) the given ``src``. See :ref:`start` for mode of operation. +Run the desired operation for this AES context. Will return a :ref:`PackedByteArray` containing the result of encrypting (or decrypting) the given ``src``. See :ref:`start()` for mode of operation. \ **Note:** The size of ``src`` must be a multiple of 16. Apply some padding if needed. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_aimmodifier3d.rst b/classes/class_aimmodifier3d.rst new file mode 100644 index 00000000000..07ca7f60284 --- /dev/null +++ b/classes/class_aimmodifier3d.rst @@ -0,0 +1,197 @@ +: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/AimModifier3D.xml. + +.. _class_AimModifier3D: + +AimModifier3D +============= + +**Inherits:** :ref:`BoneConstraint3D` **<** :ref:`SkeletonModifier3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +The **AimModifier3D** rotates a bone to look at a reference bone. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This is a simple version of :ref:`LookAtModifier3D` that only allows bone to the reference without advanced options such as angle limitation or time-based interpolation. + +The feature is simplified, but instead it is implemented with smooth tracking without euler, see :ref:`set_use_euler()`. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`setting_count` | ``0`` | + +-----------------------+------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`BoneAxis` | :ref:`get_forward_axis`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Axis` | :ref:`get_primary_rotation_axis`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_using_euler`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_using_secondary_rotation`\ (\ index\: :ref:`int`\ ) |const| | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_forward_axis`\ (\ index\: :ref:`int`, axis\: :ref:`BoneAxis`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_primary_rotation_axis`\ (\ index\: :ref:`int`, axis\: :ref:`Axis`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_use_euler`\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_use_secondary_rotation`\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AimModifier3D_property_setting_count: + +.. rst-class:: classref-property + +:ref:`int` **setting_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_setting_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_setting_count**\ (\ ) + +The number of settings in the modifier. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AimModifier3D_method_get_forward_axis: + +.. rst-class:: classref-method + +:ref:`BoneAxis` **get_forward_axis**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the forward axis of the bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_get_primary_rotation_axis: + +.. rst-class:: classref-method + +:ref:`Axis` **get_primary_rotation_axis**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the axis of the first rotation. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_is_using_euler: + +.. rst-class:: classref-method + +:ref:`bool` **is_using_euler**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if it provides rotation with using euler. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_is_using_secondary_rotation: + +.. rst-class:: classref-method + +:ref:`bool` **is_using_secondary_rotation**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if it provides rotation by two axes. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_forward_axis: + +.. rst-class:: classref-method + +|void| **set_forward_axis**\ (\ index\: :ref:`int`, axis\: :ref:`BoneAxis`\ ) :ref:`🔗` + +Sets the forward axis of the bone. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_primary_rotation_axis: + +.. rst-class:: classref-method + +|void| **set_primary_rotation_axis**\ (\ index\: :ref:`int`, axis\: :ref:`Axis`\ ) :ref:`🔗` + +Sets the axis of the first rotation. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_use_euler: + +.. rst-class:: classref-method + +|void| **set_use_euler**\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` + +If sets ``enabled`` to ``true``, it provides rotation with using euler. + +If sets ``enabled`` to ``false``, it provides rotation with using rotation by arc generated from the forward axis vector and the vector toward the reference. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AimModifier3D_method_set_use_secondary_rotation: + +.. rst-class:: classref-method + +|void| **set_use_secondary_rotation**\ (\ index\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` + +If sets ``enabled`` to ``true``, it provides rotation by two axes. It is enabled only if :ref:`is_using_euler()` is ``true``. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animatablebody2d.rst b/classes/class_animatablebody2d.rst index 91ff2f98c28..33677392102 100644 --- a/classes/class_animatablebody2d.rst +++ b/classes/class_animatablebody2d.rst @@ -23,6 +23,15 @@ An animatable 2D physics body. It can't be moved by external forces or contacts, 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-introduction-group + +Tutorials +--------- + +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + .. rst-class:: classref-reftable-group Properties @@ -48,16 +57,17 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **sync_to_physics** = ``true`` +:ref:`bool` **sync_to_physics** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_sync_to_physics**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_sync_to_physics_enabled**\ (\ ) -If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via :ref:`AnimationPlayer`, for example on moving platforms. Do **not** use together with :ref:`PhysicsBody2D.move_and_collide`. +If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via :ref:`AnimationPlayer`, for example on moving platforms. Do **not** use together with :ref:`PhysicsBody2D.move_and_collide()`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animatablebody3d.rst b/classes/class_animatablebody3d.rst index de772ac6151..1705b4d328b 100644 --- a/classes/class_animatablebody3d.rst +++ b/classes/class_animatablebody3d.rst @@ -28,11 +28,15 @@ When **AnimatableBody3D** is moved, its linear and angular velocity are estimate Tutorials --------- -- `3D Physics Tests Demo `__ +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` -- `Third Person Shooter Demo `__ +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` -- `3D Voxel Demo `__ +- `3D Physics Tests Demo `__ + +- `Third Person Shooter (TPS) Demo `__ + +- `3D Voxel Demo `__ .. rst-class:: classref-reftable-group @@ -59,16 +63,17 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **sync_to_physics** = ``true`` +:ref:`bool` **sync_to_physics** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_sync_to_physics**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_sync_to_physics_enabled**\ (\ ) -If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via :ref:`AnimationPlayer`, for example on moving platforms. Do **not** use together with :ref:`PhysicsBody3D.move_and_collide`. +If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via :ref:`AnimationPlayer`, for example on moving platforms. Do **not** use together with :ref:`PhysicsBody3D.move_and_collide()`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animatedsprite2d.rst b/classes/class_animatedsprite2d.rst index fa2086b23dd..6843d94c92d 100644 --- a/classes/class_animatedsprite2d.rst +++ b/classes/class_animatedsprite2d.rst @@ -28,7 +28,7 @@ Tutorials - :doc:`2D Sprite animation <../tutorials/2d/2d_sprite_animation>` -- `2D Dodge The Creeps Demo `__ +- `2D Dodge The Creeps Demo `__ .. rst-class:: classref-reftable-group @@ -97,7 +97,7 @@ Signals .. rst-class:: classref-signal -**animation_changed**\ (\ ) +**animation_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`animation` changes. @@ -109,7 +109,7 @@ Emitted when :ref:`animation` changes .. rst-class:: classref-signal -**animation_finished**\ (\ ) +**animation_finished**\ (\ ) :ref:`🔗` Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. @@ -123,7 +123,7 @@ Emitted when the animation reaches the end, or the start if it is played in reve .. rst-class:: classref-signal -**animation_looped**\ (\ ) +**animation_looped**\ (\ ) :ref:`🔗` Emitted when the animation loops. @@ -135,7 +135,7 @@ Emitted when the animation loops. .. rst-class:: classref-signal -**frame_changed**\ (\ ) +**frame_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`frame` changes. @@ -147,7 +147,7 @@ Emitted when :ref:`frame` changes. .. rst-class:: classref-signal -**sprite_frames_changed**\ (\ ) +**sprite_frames_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`sprite_frames` changes. @@ -164,7 +164,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`StringName` **animation** = ``&"default"`` +:ref:`StringName` **animation** = ``&"default"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -181,7 +181,7 @@ The current animation from the :ref:`sprite_frames` **autoplay** = ``""`` +:ref:`String` **autoplay** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,7 +198,7 @@ The key of the animation to play when the scene loads. .. rst-class:: classref-property -:ref:`bool` **centered** = ``true`` +:ref:`bool` **centered** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -217,7 +217,7 @@ If ``true``, texture will be centered. .. rst-class:: classref-property -:ref:`bool` **flip_h** = ``false`` +:ref:`bool` **flip_h** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -234,7 +234,7 @@ If ``true``, texture is flipped horizontally. .. rst-class:: classref-property -:ref:`bool` **flip_v** = ``false`` +:ref:`bool` **flip_v** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -251,14 +251,14 @@ If ``true``, texture is flipped vertically. .. rst-class:: classref-property -:ref:`int` **frame** = ``0`` +:ref:`int` **frame** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_frame**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_frame**\ (\ ) -The displayed animation frame's index. Setting this property also resets :ref:`frame_progress`. If this is not desired, use :ref:`set_frame_and_progress`. +The displayed animation frame's index. Setting this property also resets :ref:`frame_progress`. If this is not desired, use :ref:`set_frame_and_progress()`. .. rst-class:: classref-item-separator @@ -268,7 +268,7 @@ The displayed animation frame's index. Setting this property also resets :ref:`f .. rst-class:: classref-property -:ref:`float` **frame_progress** = ``0.0`` +:ref:`float` **frame_progress** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -285,7 +285,7 @@ The progress value between ``0.0`` and ``1.0`` until the current frame transitio .. rst-class:: classref-property -:ref:`Vector2` **offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -302,7 +302,7 @@ The texture's drawing offset. .. rst-class:: classref-property -:ref:`float` **speed_scale** = ``1.0`` +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -321,7 +321,7 @@ If set to a negative value, the animation is played in reverse. If set to ``0``, .. rst-class:: classref-property -:ref:`SpriteFrames` **sprite_frames** +:ref:`SpriteFrames` **sprite_frames** :ref:`🔗` .. rst-class:: classref-property-setget @@ -343,9 +343,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_playing_speed**\ (\ ) |const| +:ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` -Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play` method. +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play()` method. Returns a negative value if the current animation is playing backwards. @@ -357,7 +357,7 @@ Returns a negative value if the current animation is playing backwards. .. rst-class:: classref-method -:ref:`bool` **is_playing**\ (\ ) |const| +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale` and/or ``custom_speed`` are ``0``). @@ -369,11 +369,11 @@ Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale .. rst-class:: classref-method -|void| **pause**\ (\ ) +|void| **pause**\ (\ ) :ref:`🔗` -Pauses the currently playing animation. The :ref:`frame` and :ref:`frame_progress` will be kept and calling :ref:`play` or :ref:`play_backwards` without arguments will resume the animation from the current playback position. +Pauses the currently playing animation. The :ref:`frame` and :ref:`frame_progress` will be kept and calling :ref:`play()` or :ref:`play_backwards()` without arguments will resume the animation from the current playback position. -See also :ref:`stop`. +See also :ref:`stop()`. .. rst-class:: classref-item-separator @@ -383,9 +383,9 @@ See also :ref:`stop`. .. rst-class:: classref-method -|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) +|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` -Plays the animation with key ``name``. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards`). +Plays the animation with key ``name``. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards()`). If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused. @@ -397,11 +397,11 @@ If this method is called with that same animation ``name``, or with no ``name`` .. rst-class:: classref-method -|void| **play_backwards**\ (\ name\: :ref:`StringName` = &""\ ) +|void| **play_backwards**\ (\ name\: :ref:`StringName` = &""\ ) :ref:`🔗` Plays the animation with key ``name`` in reverse. -This method is a shorthand for :ref:`play` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. +This method is a shorthand for :ref:`play()` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. .. rst-class:: classref-item-separator @@ -411,20 +411,17 @@ This method is a shorthand for :ref:`play` w .. rst-class:: classref-method -|void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) +|void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) :ref:`🔗` -The setter of :ref:`frame` resets the :ref:`frame_progress` to ``0.0`` implicitly, but this method avoids that. +Sets :ref:`frame` and :ref:`frame_progress` to the given values. Unlike setting :ref:`frame`, this method does not reset the :ref:`frame_progress` to ``0.0`` implicitly. -This is useful when you want to carry over the current :ref:`frame_progress` to another :ref:`frame`. - -\ **Example:**\ +\ **Example:** Change the animation while keeping the same :ref:`frame` and :ref:`frame_progress`: .. tabs:: .. code-tab:: gdscript - # Change the animation with keeping the frame index and progress. var current_frame = animated_sprite.get_frame() var current_progress = animated_sprite.get_frame_progress() animated_sprite.play("walk_another_skin") @@ -440,11 +437,12 @@ This is useful when you want to carry over the current :ref:`frame_progress` -Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause`. +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause()`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animatedsprite3d.rst b/classes/class_animatedsprite3d.rst index 2611ed6cf24..9e2d066f4ce 100644 --- a/classes/class_animatedsprite3d.rst +++ b/classes/class_animatedsprite3d.rst @@ -87,7 +87,7 @@ Signals .. rst-class:: classref-signal -**animation_changed**\ (\ ) +**animation_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`animation` changes. @@ -99,7 +99,7 @@ Emitted when :ref:`animation` changes .. rst-class:: classref-signal -**animation_finished**\ (\ ) +**animation_finished**\ (\ ) :ref:`🔗` Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. @@ -113,7 +113,7 @@ Emitted when the animation reaches the end, or the start if it is played in reve .. rst-class:: classref-signal -**animation_looped**\ (\ ) +**animation_looped**\ (\ ) :ref:`🔗` Emitted when the animation loops. @@ -125,7 +125,7 @@ Emitted when the animation loops. .. rst-class:: classref-signal -**frame_changed**\ (\ ) +**frame_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`frame` changes. @@ -137,7 +137,7 @@ Emitted when :ref:`frame` changes. .. rst-class:: classref-signal -**sprite_frames_changed**\ (\ ) +**sprite_frames_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`sprite_frames` changes. @@ -154,7 +154,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`StringName` **animation** = ``&"default"`` +:ref:`StringName` **animation** = ``&"default"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -171,7 +171,7 @@ The current animation from the :ref:`sprite_frames` **autoplay** = ``""`` +:ref:`String` **autoplay** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -188,14 +188,14 @@ The key of the animation to play when the scene loads. .. rst-class:: classref-property -:ref:`int` **frame** = ``0`` +:ref:`int` **frame** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_frame**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_frame**\ (\ ) -The displayed animation frame's index. Setting this property also resets :ref:`frame_progress`. If this is not desired, use :ref:`set_frame_and_progress`. +The displayed animation frame's index. Setting this property also resets :ref:`frame_progress`. If this is not desired, use :ref:`set_frame_and_progress()`. .. rst-class:: classref-item-separator @@ -205,7 +205,7 @@ The displayed animation frame's index. Setting this property also resets :ref:`f .. rst-class:: classref-property -:ref:`float` **frame_progress** = ``0.0`` +:ref:`float` **frame_progress** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -222,7 +222,7 @@ The progress value between ``0.0`` and ``1.0`` until the current frame transitio .. rst-class:: classref-property -:ref:`float` **speed_scale** = ``1.0`` +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -241,7 +241,7 @@ If set to a negative value, the animation is played in reverse. If set to ``0``, .. rst-class:: classref-property -:ref:`SpriteFrames` **sprite_frames** +:ref:`SpriteFrames` **sprite_frames** :ref:`🔗` .. rst-class:: classref-property-setget @@ -263,9 +263,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_playing_speed**\ (\ ) |const| +:ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` -Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play` method. +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play()` method. Returns a negative value if the current animation is playing backwards. @@ -277,7 +277,7 @@ Returns a negative value if the current animation is playing backwards. .. rst-class:: classref-method -:ref:`bool` **is_playing**\ (\ ) |const| +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale` and/or ``custom_speed`` are ``0``). @@ -289,11 +289,11 @@ Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale .. rst-class:: classref-method -|void| **pause**\ (\ ) +|void| **pause**\ (\ ) :ref:`🔗` -Pauses the currently playing animation. The :ref:`frame` and :ref:`frame_progress` will be kept and calling :ref:`play` or :ref:`play_backwards` without arguments will resume the animation from the current playback position. +Pauses the currently playing animation. The :ref:`frame` and :ref:`frame_progress` will be kept and calling :ref:`play()` or :ref:`play_backwards()` without arguments will resume the animation from the current playback position. -See also :ref:`stop`. +See also :ref:`stop()`. .. rst-class:: classref-item-separator @@ -303,9 +303,9 @@ See also :ref:`stop`. .. rst-class:: classref-method -|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) +|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` -Plays the animation with key ``name``. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards`). +Plays the animation with key ``name``. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards()`). If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused. @@ -317,11 +317,11 @@ If this method is called with that same animation ``name``, or with no ``name`` .. rst-class:: classref-method -|void| **play_backwards**\ (\ name\: :ref:`StringName` = &""\ ) +|void| **play_backwards**\ (\ name\: :ref:`StringName` = &""\ ) :ref:`🔗` Plays the animation with key ``name`` in reverse. -This method is a shorthand for :ref:`play` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. +This method is a shorthand for :ref:`play()` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. .. rst-class:: classref-item-separator @@ -331,20 +331,17 @@ This method is a shorthand for :ref:`play` w .. rst-class:: classref-method -|void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) +|void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) :ref:`🔗` -The setter of :ref:`frame` resets the :ref:`frame_progress` to ``0.0`` implicitly, but this method avoids that. +Sets :ref:`frame` and :ref:`frame_progress` to the given values. Unlike setting :ref:`frame`, this method does not reset the :ref:`frame_progress` to ``0.0`` implicitly. -This is useful when you want to carry over the current :ref:`frame_progress` to another :ref:`frame`. - -\ **Example:**\ +\ **Example:** Change the animation while keeping the same :ref:`frame` and :ref:`frame_progress`: .. tabs:: .. code-tab:: gdscript - # Change the animation with keeping the frame index and progress. var current_frame = animated_sprite.get_frame() var current_progress = animated_sprite.get_frame_progress() animated_sprite.play("walk_another_skin") @@ -360,11 +357,12 @@ This is useful when you want to carry over the current :ref:`frame_progress` -Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause`. +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause()`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animatedtexture.rst b/classes/class_animatedtexture.rst index 61d15057e2f..7a8e812f059 100644 --- a/classes/class_animatedtexture.rst +++ b/classes/class_animatedtexture.rst @@ -23,7 +23,7 @@ Description **AnimatedTexture** is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame. Unlike :ref:`AnimationPlayer` or :ref:`AnimatedSprite2D`, it isn't a :ref:`Node`, but has the advantage of being usable anywhere a :ref:`Texture2D` resource can be used, e.g. in a :ref:`TileSet`. -The playback of the animation is controlled by the :ref:`speed_scale` property, as well as each frame's duration (see :ref:`set_frame_duration`). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame. +The playback of the animation is controlled by the :ref:`speed_scale` property, as well as each frame's duration (see :ref:`set_frame_duration()`). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame. \ **AnimatedTexture** currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one. @@ -84,7 +84,7 @@ Constants .. rst-class:: classref-constant -**MAX_FRAMES** = ``256`` +**MAX_FRAMES** = ``256`` :ref:`🔗` The maximum number of frames supported by **AnimatedTexture**. If you need more frames in your animation, use :ref:`AnimationPlayer` or :ref:`AnimatedSprite2D`. @@ -101,7 +101,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **current_frame** +:ref:`int` **current_frame** :ref:`🔗` .. rst-class:: classref-property-setget @@ -118,14 +118,14 @@ Sets the currently visible frame of the texture. Setting this frame while playin .. rst-class:: classref-property -:ref:`int` **frames** = ``1`` +:ref:`int` **frames** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_frames**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_frames**\ (\ ) -Number of frames to use in the animation. While you can create the frames independently with :ref:`set_frame_texture`, you need to set this value for the animation to take new frames into account. The maximum number of frames is :ref:`MAX_FRAMES`. +Number of frames to use in the animation. While you can create the frames independently with :ref:`set_frame_texture()`, you need to set this value for the animation to take new frames into account. The maximum number of frames is :ref:`MAX_FRAMES`. .. rst-class:: classref-item-separator @@ -135,7 +135,7 @@ Number of frames to use in the animation. While you can create the frames indepe .. rst-class:: classref-property -:ref:`bool` **one_shot** = ``false`` +:ref:`bool` **one_shot** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -152,7 +152,7 @@ If ``true``, the animation will only play once and will not loop back to the fir .. rst-class:: classref-property -:ref:`bool` **pause** = ``false`` +:ref:`bool` **pause** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -169,7 +169,7 @@ If ``true``, the animation will pause where it currently is (i.e. at :ref:`curre .. rst-class:: classref-property -:ref:`float` **speed_scale** = ``1.0`` +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -191,7 +191,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_frame_duration**\ (\ frame\: :ref:`int`\ ) |const| +:ref:`float` **get_frame_duration**\ (\ frame\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given ``frame``'s duration, in seconds. @@ -203,7 +203,7 @@ Returns the given ``frame``'s duration, in seconds. .. rst-class:: classref-method -:ref:`Texture2D` **get_frame_texture**\ (\ frame\: :ref:`int`\ ) |const| +:ref:`Texture2D` **get_frame_texture**\ (\ frame\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given frame's :ref:`Texture2D`. @@ -215,7 +215,7 @@ Returns the given frame's :ref:`Texture2D`. .. rst-class:: classref-method -|void| **set_frame_duration**\ (\ frame\: :ref:`int`, duration\: :ref:`float`\ ) +|void| **set_frame_duration**\ (\ frame\: :ref:`int`, duration\: :ref:`float`\ ) :ref:`🔗` Sets the duration of any given ``frame``. The final duration is affected by the :ref:`speed_scale`. If set to ``0``, the frame is skipped during playback. @@ -227,13 +227,14 @@ Sets the duration of any given ``frame``. The final duration is affected by the .. rst-class:: classref-method -|void| **set_frame_texture**\ (\ frame\: :ref:`int`, texture\: :ref:`Texture2D`\ ) +|void| **set_frame_texture**\ (\ frame\: :ref:`int`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` Assigns a :ref:`Texture2D` to the given frame. Frame IDs start at 0, so the first frame has ID 0, and the last frame of the animation has ID :ref:`frames` - 1. You can define any number of textures up to :ref:`MAX_FRAMES`, but keep in mind that only frames from 0 to :ref:`frames` - 1 will be part of the animation. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animation.rst b/classes/class_animation.rst index 3fc6a711bb2..da4032bc928 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -67,13 +67,15 @@ Properties .. table:: :widths: auto - +------------------------------------------+------------------------------------------------------+---------+ - | :ref:`float` | :ref:`length` | ``1.0`` | - +------------------------------------------+------------------------------------------------------+---------+ - | :ref:`LoopMode` | :ref:`loop_mode` | ``0`` | - +------------------------------------------+------------------------------------------------------+---------+ - | :ref:`float` | :ref:`step` | ``0.1`` | - +------------------------------------------+------------------------------------------------------+---------+ + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`bool` | :ref:`capture_included` | ``false`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`float` | :ref:`length` | ``1.0`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`LoopMode` | :ref:`loop_mode` | ``0`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ + | :ref:`float` | :ref:`step` | ``0.033333335`` | + +------------------------------------------+--------------------------------------------------------------------+-----------------+ .. rst-class:: classref-reftable-group @@ -83,6 +85,8 @@ Methods .. table:: :widths: auto + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_marker`\ (\ name\: :ref:`StringName`, time\: :ref:`float`\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`add_track`\ (\ type\: :ref:`TrackType`, at_position\: :ref:`int` = -1\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -138,16 +142,34 @@ Methods +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`find_track`\ (\ path\: :ref:`NodePath`, type\: :ref:`TrackType`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_marker_at_time`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`get_marker_color`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_marker_names`\ (\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_marker_time`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_next_marker`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_prev_marker`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_track_count`\ (\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_marker`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`method_track_get_name`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`method_track_get_params`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`optimize`\ (\ allowed_velocity_err\: :ref:`float` = 0.01, allowed_angular_err\: :ref:`float` = 0.01, precision\: :ref:`int` = 3\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`position_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, position\: :ref:`Vector3`\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`position_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_marker`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_track`\ (\ track_idx\: :ref:`int`\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rotation_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, rotation\: :ref:`Quaternion`\ ) | @@ -158,7 +180,9 @@ Methods +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`scale_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`track_find_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false\ ) |const| | + | |void| | :ref:`set_marker_color`\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`track_find_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false, backward\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`track_get_interpolation_loop_wrap`\ (\ track_idx\: :ref:`int`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -232,7 +256,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **TrackType**: +enum **TrackType**: :ref:`🔗` .. _class_Animation_constant_TYPE_VALUE: @@ -314,7 +338,7 @@ Animation tracks play animations in other :ref:`AnimationPlayer` .. _class_Animation_constant_INTERPOLATION_NEAREST: @@ -368,7 +392,7 @@ Cubic interpolation with shortest path rotation. .. rst-class:: classref-enumeration -enum **UpdateMode**: +enum **UpdateMode**: :ref:`🔗` .. _class_Animation_constant_UPDATE_CONTINUOUS: @@ -392,7 +416,7 @@ Update at the keyframes. :ref:`UpdateMode` **UPDATE_CAPTURE** = ``2`` -Same as :ref:`UPDATE_CONTINUOUS` but works as a flag to capture the value of the current object and perform interpolation in some methods. See also :ref:`AnimationMixer.capture` and :ref:`AnimationPlayer.play_with_capture`. +Same as :ref:`UPDATE_CONTINUOUS` but works as a flag to capture the value of the current object and perform interpolation in some methods. See also :ref:`AnimationMixer.capture()`, :ref:`AnimationPlayer.playback_auto_capture`, and :ref:`AnimationPlayer.play_with_capture()`. .. rst-class:: classref-item-separator @@ -402,7 +426,7 @@ Same as :ref:`UPDATE_CONTINUOUS` but .. rst-class:: classref-enumeration -enum **LoopMode**: +enum **LoopMode**: :ref:`🔗` .. _class_Animation_constant_LOOP_NONE: @@ -436,7 +460,7 @@ Repeats playback and reverse playback at both ends of the animation. .. rst-class:: classref-enumeration -enum **LoopedFlag**: +enum **LoopedFlag**: :ref:`🔗` .. _class_Animation_constant_LOOPED_FLAG_NONE: @@ -470,7 +494,7 @@ This flag indicates that the animation has reached the start of the animation an .. rst-class:: classref-enumeration -enum **FindMode**: +enum **FindMode**: :ref:`🔗` .. _class_Animation_constant_FIND_MODE_NEAREST: @@ -505,11 +529,27 @@ Finds only the key with matching the time. Property Descriptions --------------------- +.. _class_Animation_property_capture_included: + +.. rst-class:: classref-property + +:ref:`bool` **capture_included** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`bool` **is_capture_included**\ (\ ) + +Returns ``true`` if the capture track is included. This is a cached readonly value for performance. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_property_length: .. rst-class:: classref-property -:ref:`float` **length** = ``1.0`` +:ref:`float` **length** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -528,14 +568,14 @@ The total length of the animation (in seconds). .. rst-class:: classref-property -:ref:`LoopMode` **loop_mode** = ``0`` +:ref:`LoopMode` **loop_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) - :ref:`LoopMode` **get_loop_mode**\ (\ ) -Determines the behavior of both ends of the animation timeline during animation playback. This is used for correct interpolation of animation cycles, and for hinting the player that it must restart the animation. +Determines the behavior of both ends of the animation timeline during animation playback. This indicates whether and how the animation should be restarted, and is also used to correctly interpolate animation cycles. .. rst-class:: classref-item-separator @@ -545,7 +585,7 @@ Determines the behavior of both ends of the animation timeline during animation .. rst-class:: classref-property -:ref:`float` **step** = ``0.1`` +:ref:`float` **step** = ``0.033333335`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -563,11 +603,23 @@ The animation step value. Method Descriptions ------------------- +.. _class_Animation_method_add_marker: + +.. rst-class:: classref-method + +|void| **add_marker**\ (\ name\: :ref:`StringName`, time\: :ref:`float`\ ) :ref:`🔗` + +Adds a marker to this Animation. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_add_track: .. rst-class:: classref-method -:ref:`int` **add_track**\ (\ type\: :ref:`TrackType`, at_position\: :ref:`int` = -1\ ) +:ref:`int` **add_track**\ (\ type\: :ref:`TrackType`, at_position\: :ref:`int` = -1\ ) :ref:`🔗` Adds a track to the Animation. @@ -579,7 +631,7 @@ Adds a track to the Animation. .. rst-class:: classref-method -:ref:`StringName` **animation_track_get_key_animation**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`StringName` **animation_track_get_key_animation**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the animation name at the key identified by ``key_idx``. The ``track_idx`` must be the index of an Animation Track. @@ -591,7 +643,7 @@ Returns the animation name at the key identified by ``key_idx``. The ``track_idx .. rst-class:: classref-method -:ref:`int` **animation_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, animation\: :ref:`StringName`\ ) +:ref:`int` **animation_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, animation\: :ref:`StringName`\ ) :ref:`🔗` Inserts a key with value ``animation`` at the given ``time`` (in seconds). The ``track_idx`` must be the index of an Animation Track. @@ -603,7 +655,7 @@ Inserts a key with value ``animation`` at the given ``time`` (in seconds). The ` .. rst-class:: classref-method -|void| **animation_track_set_key_animation**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, animation\: :ref:`StringName`\ ) +|void| **animation_track_set_key_animation**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, animation\: :ref:`StringName`\ ) :ref:`🔗` Sets the key identified by ``key_idx`` to value ``animation``. The ``track_idx`` must be the index of an Animation Track. @@ -615,7 +667,7 @@ Sets the key identified by ``key_idx`` to value ``animation``. The ``track_idx`` .. rst-class:: classref-method -:ref:`float` **audio_track_get_key_end_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`float` **audio_track_get_key_end_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the end offset of the key identified by ``key_idx``. The ``track_idx`` must be the index of an Audio Track. @@ -629,7 +681,7 @@ End offset is the number of seconds cut off at the ending of the audio stream. .. rst-class:: classref-method -:ref:`float` **audio_track_get_key_start_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`float` **audio_track_get_key_start_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the start offset of the key identified by ``key_idx``. The ``track_idx`` must be the index of an Audio Track. @@ -643,7 +695,7 @@ Start offset is the number of seconds cut off at the beginning of the audio stre .. rst-class:: classref-method -:ref:`Resource` **audio_track_get_key_stream**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`Resource` **audio_track_get_key_stream**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the audio stream of the key identified by ``key_idx``. The ``track_idx`` must be the index of an Audio Track. @@ -655,7 +707,7 @@ Returns the audio stream of the key identified by ``key_idx``. The ``track_idx`` .. rst-class:: classref-method -:ref:`int` **audio_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, stream\: :ref:`Resource`, start_offset\: :ref:`float` = 0, end_offset\: :ref:`float` = 0\ ) +:ref:`int` **audio_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, stream\: :ref:`Resource`, start_offset\: :ref:`float` = 0, end_offset\: :ref:`float` = 0\ ) :ref:`🔗` Inserts an Audio Track key at the given ``time`` in seconds. The ``track_idx`` must be the index of an Audio Track. @@ -669,7 +721,7 @@ Inserts an Audio Track key at the given ``time`` in seconds. The ``track_idx`` m .. rst-class:: classref-method -:ref:`bool` **audio_track_is_use_blend**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`bool` **audio_track_is_use_blend**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if the track at ``track_idx`` will be blended with other animations. @@ -681,7 +733,7 @@ Returns ``true`` if the track at ``track_idx`` will be blended with other animat .. rst-class:: classref-method -|void| **audio_track_set_key_end_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) +|void| **audio_track_set_key_end_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) :ref:`🔗` Sets the end offset of the key identified by ``key_idx`` to value ``offset``. The ``track_idx`` must be the index of an Audio Track. @@ -693,7 +745,7 @@ Sets the end offset of the key identified by ``key_idx`` to value ``offset``. Th .. rst-class:: classref-method -|void| **audio_track_set_key_start_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) +|void| **audio_track_set_key_start_offset**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, offset\: :ref:`float`\ ) :ref:`🔗` Sets the start offset of the key identified by ``key_idx`` to value ``offset``. The ``track_idx`` must be the index of an Audio Track. @@ -705,7 +757,7 @@ Sets the start offset of the key identified by ``key_idx`` to value ``offset``. .. rst-class:: classref-method -|void| **audio_track_set_key_stream**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, stream\: :ref:`Resource`\ ) +|void| **audio_track_set_key_stream**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, stream\: :ref:`Resource`\ ) :ref:`🔗` Sets the stream of the key identified by ``key_idx`` to value ``stream``. The ``track_idx`` must be the index of an Audio Track. @@ -717,7 +769,7 @@ Sets the stream of the key identified by ``key_idx`` to value ``stream``. The `` .. rst-class:: classref-method -|void| **audio_track_set_use_blend**\ (\ track_idx\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **audio_track_set_use_blend**\ (\ track_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` Sets whether the track will be blended with other animations. If ``true``, the audio playback volume changes depending on the blend value. @@ -729,7 +781,7 @@ Sets whether the track will be blended with other animations. If ``true``, the a .. rst-class:: classref-method -:ref:`Vector2` **bezier_track_get_key_in_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`Vector2` **bezier_track_get_key_in_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the in handle of the key identified by ``key_idx``. The ``track_idx`` must be the index of a Bezier Track. @@ -741,7 +793,7 @@ Returns the in handle of the key identified by ``key_idx``. The ``track_idx`` mu .. rst-class:: classref-method -:ref:`Vector2` **bezier_track_get_key_out_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`Vector2` **bezier_track_get_key_out_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the out handle of the key identified by ``key_idx``. The ``track_idx`` must be the index of a Bezier Track. @@ -753,7 +805,7 @@ Returns the out handle of the key identified by ``key_idx``. The ``track_idx`` m .. rst-class:: classref-method -:ref:`float` **bezier_track_get_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`float` **bezier_track_get_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the value of the key identified by ``key_idx``. The ``track_idx`` must be the index of a Bezier Track. @@ -765,7 +817,7 @@ Returns the value of the key identified by ``key_idx``. The ``track_idx`` must b .. rst-class:: classref-method -:ref:`int` **bezier_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, value\: :ref:`float`, in_handle\: :ref:`Vector2` = Vector2(0, 0), out_handle\: :ref:`Vector2` = Vector2(0, 0)\ ) +:ref:`int` **bezier_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, value\: :ref:`float`, in_handle\: :ref:`Vector2` = Vector2(0, 0), out_handle\: :ref:`Vector2` = Vector2(0, 0)\ ) :ref:`🔗` Inserts a Bezier Track key at the given ``time`` in seconds. The ``track_idx`` must be the index of a Bezier Track. @@ -779,7 +831,7 @@ Inserts a Bezier Track key at the given ``time`` in seconds. The ``track_idx`` m .. rst-class:: classref-method -:ref:`float` **bezier_track_interpolate**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) |const| +:ref:`float` **bezier_track_interpolate**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) |const| :ref:`🔗` Returns the interpolated value at the given ``time`` (in seconds). The ``track_idx`` must be the index of a Bezier Track. @@ -791,7 +843,7 @@ Returns the interpolated value at the given ``time`` (in seconds). The ``track_i .. rst-class:: classref-method -|void| **bezier_track_set_key_in_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, in_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) +|void| **bezier_track_set_key_in_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, in_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) :ref:`🔗` Sets the in handle of the key identified by ``key_idx`` to value ``in_handle``. The ``track_idx`` must be the index of a Bezier Track. @@ -803,7 +855,7 @@ Sets the in handle of the key identified by ``key_idx`` to value ``in_handle``. .. rst-class:: classref-method -|void| **bezier_track_set_key_out_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, out_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) +|void| **bezier_track_set_key_out_handle**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, out_handle\: :ref:`Vector2`, balanced_value_time_ratio\: :ref:`float` = 1.0\ ) :ref:`🔗` Sets the out handle of the key identified by ``key_idx`` to value ``out_handle``. The ``track_idx`` must be the index of a Bezier Track. @@ -815,7 +867,7 @@ Sets the out handle of the key identified by ``key_idx`` to value ``out_handle`` .. rst-class:: classref-method -|void| **bezier_track_set_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, value\: :ref:`float`\ ) +|void| **bezier_track_set_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, value\: :ref:`float`\ ) :ref:`🔗` Sets the value of the key identified by ``key_idx`` to the given value. The ``track_idx`` must be the index of a Bezier Track. @@ -827,7 +879,7 @@ Sets the value of the key identified by ``key_idx`` to the given value. The ``tr .. rst-class:: classref-method -:ref:`int` **blend_shape_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, amount\: :ref:`float`\ ) +:ref:`int` **blend_shape_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, amount\: :ref:`float`\ ) :ref:`🔗` Inserts a key in a given blend shape track. Returns the key index. @@ -839,7 +891,7 @@ Inserts a key in a given blend shape track. Returns the key index. .. rst-class:: classref-method -:ref:`float` **blend_shape_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| +:ref:`float` **blend_shape_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the interpolated blend shape value at the given time (in seconds). The ``track_idx`` must be the index of a blend shape track. @@ -851,7 +903,7 @@ Returns the interpolated blend shape value at the given time (in seconds). The ` .. rst-class:: classref-method -|void| **clear**\ (\ ) +|void| **clear**\ (\ ) :ref:`🔗` Clear the animation (clear all tracks and reset all). @@ -863,9 +915,9 @@ Clear the animation (clear all tracks and reset all). .. rst-class:: classref-method -|void| **compress**\ (\ page_size\: :ref:`int` = 8192, fps\: :ref:`int` = 120, split_tolerance\: :ref:`float` = 4.0\ ) +|void| **compress**\ (\ page_size\: :ref:`int` = 8192, fps\: :ref:`int` = 120, split_tolerance\: :ref:`float` = 4.0\ ) :ref:`🔗` -Compress the animation and all its tracks in-place. This will make :ref:`track_is_compressed` return ``true`` once called on this **Animation**. Compressed tracks require less memory to be played, and are designed to be used for complex 3D animations (such as cutscenes) imported from external 3D software. Compression is lossy, but the difference is usually not noticeable in real world conditions. +Compress the animation and all its tracks in-place. This will make :ref:`track_is_compressed()` return ``true`` once called on this **Animation**. Compressed tracks require less memory to be played, and are designed to be used for complex 3D animations (such as cutscenes) imported from external 3D software. Compression is lossy, but the difference is usually not noticeable in real world conditions. \ **Note:** Compressed tracks have various limitations (such as not being editable from the editor), so only use compressed animations if you actually need them. @@ -877,7 +929,7 @@ Compress the animation and all its tracks in-place. This will make :ref:`track_i .. rst-class:: classref-method -|void| **copy_track**\ (\ track_idx\: :ref:`int`, to_animation\: :ref:`Animation`\ ) +|void| **copy_track**\ (\ track_idx\: :ref:`int`, to_animation\: :ref:`Animation`\ ) :ref:`🔗` Adds a new track to ``to_animation`` that is a copy of the given track from this animation. @@ -889,7 +941,7 @@ Adds a new track to ``to_animation`` that is a copy of the given track from this .. rst-class:: classref-method -:ref:`int` **find_track**\ (\ path\: :ref:`NodePath`, type\: :ref:`TrackType`\ ) |const| +:ref:`int` **find_track**\ (\ path\: :ref:`NodePath`, type\: :ref:`TrackType`\ ) |const| :ref:`🔗` Returns the index of the specified track. If the track is not found, return -1. @@ -897,11 +949,83 @@ Returns the index of the specified track. If the track is not found, return -1. ---- +.. _class_Animation_method_get_marker_at_time: + +.. rst-class:: classref-method + +:ref:`StringName` **get_marker_at_time**\ (\ time\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the name of the marker located at the given time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_color: + +.. rst-class:: classref-method + +:ref:`Color` **get_marker_color**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the given marker's color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_names: + +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_marker_names**\ (\ ) |const| :ref:`🔗` + +Returns every marker in this Animation, sorted ascending by time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_time: + +.. rst-class:: classref-method + +:ref:`float` **get_marker_time**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the given marker's time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_next_marker: + +.. rst-class:: classref-method + +:ref:`StringName` **get_next_marker**\ (\ time\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the closest marker that comes after the given time. If no such marker exists, an empty string is returned. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_prev_marker: + +.. rst-class:: classref-method + +:ref:`StringName` **get_prev_marker**\ (\ time\: :ref:`float`\ ) |const| :ref:`🔗` + +Returns the closest marker that comes before the given time. If no such marker exists, an empty string is returned. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_get_track_count: .. rst-class:: classref-method -:ref:`int` **get_track_count**\ (\ ) |const| +:ref:`int` **get_track_count**\ (\ ) |const| :ref:`🔗` Returns the amount of tracks in the animation. @@ -909,11 +1033,23 @@ Returns the amount of tracks in the animation. ---- +.. _class_Animation_method_has_marker: + +.. rst-class:: classref-method + +:ref:`bool` **has_marker**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns ``true`` if this Animation contains a marker with the given name. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_method_track_get_name: .. rst-class:: classref-method -:ref:`StringName` **method_track_get_name**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`StringName` **method_track_get_name**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the method name of a method track. @@ -925,7 +1061,7 @@ Returns the method name of a method track. .. rst-class:: classref-method -:ref:`Array` **method_track_get_params**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`Array` **method_track_get_params**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the arguments values to be called on a method track for a given key in a given track. @@ -933,11 +1069,23 @@ Returns the arguments values to be called on a method track for a given key in a ---- +.. _class_Animation_method_optimize: + +.. rst-class:: classref-method + +|void| **optimize**\ (\ allowed_velocity_err\: :ref:`float` = 0.01, allowed_angular_err\: :ref:`float` = 0.01, precision\: :ref:`int` = 3\ ) :ref:`🔗` + +Optimize the animation and all its tracks in-place. This will preserve only as many keys as are necessary to keep the animation within the specified bounds. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_position_track_insert_key: .. rst-class:: classref-method -:ref:`int` **position_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, position\: :ref:`Vector3`\ ) +:ref:`int` **position_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, position\: :ref:`Vector3`\ ) :ref:`🔗` Inserts a key in a given 3D position track. Returns the key index. @@ -949,7 +1097,7 @@ Inserts a key in a given 3D position track. Returns the key index. .. rst-class:: classref-method -:ref:`Vector3` **position_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| +:ref:`Vector3` **position_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the interpolated position value at the given time (in seconds). The ``track_idx`` must be the index of a 3D position track. @@ -957,11 +1105,23 @@ Returns the interpolated position value at the given time (in seconds). The ``tr ---- +.. _class_Animation_method_remove_marker: + +.. rst-class:: classref-method + +|void| **remove_marker**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` + +Removes the marker with the given name from this Animation. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_remove_track: .. rst-class:: classref-method -|void| **remove_track**\ (\ track_idx\: :ref:`int`\ ) +|void| **remove_track**\ (\ track_idx\: :ref:`int`\ ) :ref:`🔗` Removes a track by specifying the track index. @@ -973,7 +1133,7 @@ Removes a track by specifying the track index. .. rst-class:: classref-method -:ref:`int` **rotation_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, rotation\: :ref:`Quaternion`\ ) +:ref:`int` **rotation_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, rotation\: :ref:`Quaternion`\ ) :ref:`🔗` Inserts a key in a given 3D rotation track. Returns the key index. @@ -985,7 +1145,7 @@ Inserts a key in a given 3D rotation track. Returns the key index. .. rst-class:: classref-method -:ref:`Quaternion` **rotation_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| +:ref:`Quaternion` **rotation_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the interpolated rotation value at the given time (in seconds). The ``track_idx`` must be the index of a 3D rotation track. @@ -997,7 +1157,7 @@ Returns the interpolated rotation value at the given time (in seconds). The ``tr .. rst-class:: classref-method -:ref:`int` **scale_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, scale\: :ref:`Vector3`\ ) +:ref:`int` **scale_track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, scale\: :ref:`Vector3`\ ) :ref:`🔗` Inserts a key in a given 3D scale track. Returns the key index. @@ -1009,7 +1169,7 @@ Inserts a key in a given 3D scale track. Returns the key index. .. rst-class:: classref-method -:ref:`Vector3` **scale_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| +:ref:`Vector3` **scale_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the interpolated scale value at the given time (in seconds). The ``track_idx`` must be the index of a 3D scale track. @@ -1017,16 +1177,32 @@ Returns the interpolated scale value at the given time (in seconds). The ``track ---- +.. _class_Animation_method_set_marker_color: + +.. rst-class:: classref-method + +|void| **set_marker_color**\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) :ref:`🔗` + +Sets the given marker's color. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_track_find_key: .. rst-class:: classref-method -:ref:`int` **track_find_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false\ ) |const| +:ref:`int` **track_find_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` Finds the key index by time in a given track. Optionally, only find it if the approx/exact time is given. If ``limit`` is ``true``, it does not return keys outside the animation range. +If ``backward`` is ``true``, the direction is reversed in methods that rely on one directional processing. + +For example, in case ``find_mode`` is :ref:`FIND_MODE_NEAREST`, if there is no key in the current position just after seeked, the first key found is retrieved by searching before the position, but if ``backward`` is ``true``, the first key found is retrieved after the position. + .. rst-class:: classref-item-separator ---- @@ -1035,7 +1211,7 @@ If ``limit`` is ``true``, it does not return keys outside the animation range. .. rst-class:: classref-method -:ref:`bool` **track_get_interpolation_loop_wrap**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`bool` **track_get_interpolation_loop_wrap**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if the track at ``track_idx`` wraps the interpolation loop. New tracks wrap the interpolation loop by default. @@ -1047,7 +1223,7 @@ Returns ``true`` if the track at ``track_idx`` wraps the interpolation loop. New .. rst-class:: classref-method -:ref:`InterpolationType` **track_get_interpolation_type**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`InterpolationType` **track_get_interpolation_type**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the interpolation type of a given track. @@ -1059,7 +1235,7 @@ Returns the interpolation type of a given track. .. rst-class:: classref-method -:ref:`int` **track_get_key_count**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`int` **track_get_key_count**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the number of keys in a given track. @@ -1071,7 +1247,7 @@ Returns the number of keys in a given track. .. rst-class:: classref-method -:ref:`float` **track_get_key_time**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`float` **track_get_key_time**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the time at which the key is located. @@ -1083,9 +1259,9 @@ Returns the time at which the key is located. .. rst-class:: classref-method -:ref:`float` **track_get_key_transition**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`float` **track_get_key_transition**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the transition curve (easing) for a specific key (see the built-in math function :ref:`@GlobalScope.ease`). +Returns the transition curve (easing) for a specific key (see the built-in math function :ref:`@GlobalScope.ease()`). .. rst-class:: classref-item-separator @@ -1095,7 +1271,7 @@ Returns the transition curve (easing) for a specific key (see the built-in math .. rst-class:: classref-method -:ref:`Variant` **track_get_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| +:ref:`Variant` **track_get_key_value**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the value of a given key in a given track. @@ -1107,9 +1283,9 @@ Returns the value of a given key in a given track. .. rst-class:: classref-method -:ref:`NodePath` **track_get_path**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`NodePath` **track_get_path**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Gets the path of a track. For more information on the path format, see :ref:`track_set_path`. +Gets the path of a track. For more information on the path format, see :ref:`track_set_path()`. .. rst-class:: classref-item-separator @@ -1119,7 +1295,7 @@ Gets the path of a track. For more information on the path format, see :ref:`tra .. rst-class:: classref-method -:ref:`TrackType` **track_get_type**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`TrackType` **track_get_type**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Gets the type of a track. @@ -1131,7 +1307,7 @@ Gets the type of a track. .. rst-class:: classref-method -:ref:`int` **track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, key\: :ref:`Variant`, transition\: :ref:`float` = 1\ ) +:ref:`int` **track_insert_key**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, key\: :ref:`Variant`, transition\: :ref:`float` = 1\ ) :ref:`🔗` Inserts a generic key in a given track. Returns the key index. @@ -1143,9 +1319,9 @@ Inserts a generic key in a given track. Returns the key index. .. rst-class:: classref-method -:ref:`bool` **track_is_compressed**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`bool` **track_is_compressed**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns ``true`` if the track is compressed, ``false`` otherwise. See also :ref:`compress`. +Returns ``true`` if the track is compressed, ``false`` otherwise. See also :ref:`compress()`. .. rst-class:: classref-item-separator @@ -1155,7 +1331,7 @@ Returns ``true`` if the track is compressed, ``false`` otherwise. See also :ref: .. rst-class:: classref-method -:ref:`bool` **track_is_enabled**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`bool` **track_is_enabled**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if the track at index ``track_idx`` is enabled. @@ -1167,7 +1343,7 @@ Returns ``true`` if the track at index ``track_idx`` is enabled. .. rst-class:: classref-method -:ref:`bool` **track_is_imported**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`bool` **track_is_imported**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if the given track is imported. Else, return ``false``. @@ -1179,7 +1355,7 @@ Returns ``true`` if the given track is imported. Else, return ``false``. .. rst-class:: classref-method -|void| **track_move_down**\ (\ track_idx\: :ref:`int`\ ) +|void| **track_move_down**\ (\ track_idx\: :ref:`int`\ ) :ref:`🔗` Moves a track down. @@ -1191,7 +1367,7 @@ Moves a track down. .. rst-class:: classref-method -|void| **track_move_to**\ (\ track_idx\: :ref:`int`, to_idx\: :ref:`int`\ ) +|void| **track_move_to**\ (\ track_idx\: :ref:`int`, to_idx\: :ref:`int`\ ) :ref:`🔗` Changes the index position of track ``track_idx`` to the one defined in ``to_idx``. @@ -1203,7 +1379,7 @@ Changes the index position of track ``track_idx`` to the one defined in ``to_idx .. rst-class:: classref-method -|void| **track_move_up**\ (\ track_idx\: :ref:`int`\ ) +|void| **track_move_up**\ (\ track_idx\: :ref:`int`\ ) :ref:`🔗` Moves a track up. @@ -1215,7 +1391,7 @@ Moves a track up. .. rst-class:: classref-method -|void| **track_remove_key**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) +|void| **track_remove_key**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) :ref:`🔗` Removes a key by index in a given track. @@ -1227,7 +1403,7 @@ Removes a key by index in a given track. .. rst-class:: classref-method -|void| **track_remove_key_at_time**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) +|void| **track_remove_key_at_time**\ (\ track_idx\: :ref:`int`, time\: :ref:`float`\ ) :ref:`🔗` Removes a key at ``time`` in a given track. @@ -1239,7 +1415,7 @@ Removes a key at ``time`` in a given track. .. rst-class:: classref-method -|void| **track_set_enabled**\ (\ track_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) +|void| **track_set_enabled**\ (\ track_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` Enables/disables the given track. Tracks are enabled by default. @@ -1251,7 +1427,7 @@ Enables/disables the given track. Tracks are enabled by default. .. rst-class:: classref-method -|void| **track_set_imported**\ (\ track_idx\: :ref:`int`, imported\: :ref:`bool`\ ) +|void| **track_set_imported**\ (\ track_idx\: :ref:`int`, imported\: :ref:`bool`\ ) :ref:`🔗` Sets the given track as imported or not. @@ -1263,7 +1439,7 @@ Sets the given track as imported or not. .. rst-class:: classref-method -|void| **track_set_interpolation_loop_wrap**\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`bool`\ ) +|void| **track_set_interpolation_loop_wrap**\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the track at ``track_idx`` wraps the interpolation loop. @@ -1275,7 +1451,7 @@ If ``true``, the track at ``track_idx`` wraps the interpolation loop. .. rst-class:: classref-method -|void| **track_set_interpolation_type**\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`InterpolationType`\ ) +|void| **track_set_interpolation_type**\ (\ track_idx\: :ref:`int`, interpolation\: :ref:`InterpolationType`\ ) :ref:`🔗` Sets the interpolation type of a given track. @@ -1287,7 +1463,7 @@ Sets the interpolation type of a given track. .. rst-class:: classref-method -|void| **track_set_key_time**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, time\: :ref:`float`\ ) +|void| **track_set_key_time**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, time\: :ref:`float`\ ) :ref:`🔗` Sets the time of an existing key. @@ -1299,9 +1475,9 @@ Sets the time of an existing key. .. rst-class:: classref-method -|void| **track_set_key_transition**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, transition\: :ref:`float`\ ) +|void| **track_set_key_transition**\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`, transition\: :ref:`float`\ ) :ref:`🔗` -Sets the transition curve (easing) for a specific key (see the built-in math function :ref:`@GlobalScope.ease`). +Sets the transition curve (easing) for a specific key (see the built-in math function :ref:`@GlobalScope.ease()`). .. rst-class:: classref-item-separator @@ -1311,7 +1487,7 @@ Sets the transition curve (easing) for a specific key (see the built-in math fun .. rst-class:: classref-method -|void| **track_set_key_value**\ (\ track_idx\: :ref:`int`, key\: :ref:`int`, value\: :ref:`Variant`\ ) +|void| **track_set_key_value**\ (\ track_idx\: :ref:`int`, key\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` Sets the value of an existing key. @@ -1323,9 +1499,9 @@ Sets the value of an existing key. .. rst-class:: classref-method -|void| **track_set_path**\ (\ track_idx\: :ref:`int`, path\: :ref:`NodePath`\ ) +|void| **track_set_path**\ (\ track_idx\: :ref:`int`, path\: :ref:`NodePath`\ ) :ref:`🔗` -Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the parent node of the node that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. +Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the :ref:`AnimationMixer.root_node` that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local"``. @@ -1337,7 +1513,7 @@ For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local .. rst-class:: classref-method -|void| **track_swap**\ (\ track_idx\: :ref:`int`, with_idx\: :ref:`int`\ ) +|void| **track_swap**\ (\ track_idx\: :ref:`int`, with_idx\: :ref:`int`\ ) :ref:`🔗` Swaps the track ``track_idx``'s index position with the track ``with_idx``. @@ -1349,7 +1525,7 @@ Swaps the track ``track_idx``'s index position with the track ``with_idx``. .. rst-class:: classref-method -:ref:`UpdateMode` **value_track_get_update_mode**\ (\ track_idx\: :ref:`int`\ ) |const| +:ref:`UpdateMode` **value_track_get_update_mode**\ (\ track_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the update mode of a value track. @@ -1361,10 +1537,12 @@ Returns the update mode of a value track. .. rst-class:: classref-method -:ref:`Variant` **value_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| +:ref:`Variant` **value_track_interpolate**\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the interpolated value at the given time (in seconds). The ``track_idx`` must be the index of a value track. +A ``backward`` mainly affects the direction of key retrieval of the track with :ref:`UPDATE_DISCRETE` converted by :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS` to match the result with :ref:`track_find_key()`. + .. rst-class:: classref-item-separator ---- @@ -1373,11 +1551,12 @@ Returns the interpolated value at the given time (in seconds). The ``track_idx`` .. rst-class:: classref-method -|void| **value_track_set_update_mode**\ (\ track_idx\: :ref:`int`, mode\: :ref:`UpdateMode`\ ) +|void| **value_track_set_update_mode**\ (\ track_idx\: :ref:`int`, mode\: :ref:`UpdateMode`\ ) :ref:`🔗` -Sets the update mode (see :ref:`UpdateMode`) of a value track. +Sets the update mode of a value track. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationlibrary.rst b/classes/class_animationlibrary.rst index 6a2d6d212ba..73d3860bfdb 100644 --- a/classes/class_animationlibrary.rst +++ b/classes/class_animationlibrary.rst @@ -43,6 +43,8 @@ Methods +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_animation_list`\ (\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_animation_list_size`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_animation`\ (\ name\: :ref:`StringName`\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_animation`\ (\ name\: :ref:`StringName`\ ) | @@ -63,7 +65,7 @@ Signals .. rst-class:: classref-signal -**animation_added**\ (\ name\: :ref:`StringName`\ ) +**animation_added**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Emitted when an :ref:`Animation` is added, under the key ``name``. @@ -75,7 +77,7 @@ Emitted when an :ref:`Animation` is added, under the key ``name .. rst-class:: classref-signal -**animation_changed**\ (\ name\: :ref:`StringName`\ ) +**animation_changed**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Emitted when there's a change in one of the animations, e.g. tracks are added, moved or have changed paths. ``name`` is the key of the animation that was changed. @@ -89,7 +91,7 @@ See also :ref:`Resource.changed`, which this acts .. rst-class:: classref-signal -**animation_removed**\ (\ name\: :ref:`StringName`\ ) +**animation_removed**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Emitted when an :ref:`Animation` stored with the key ``name`` is removed. @@ -101,7 +103,7 @@ Emitted when an :ref:`Animation` stored with the key ``name`` i .. rst-class:: classref-signal -**animation_renamed**\ (\ name\: :ref:`StringName`, to_name\: :ref:`StringName`\ ) +**animation_renamed**\ (\ name\: :ref:`StringName`, to_name\: :ref:`StringName`\ ) :ref:`🔗` Emitted when the key for an :ref:`Animation` is changed, from ``name`` to ``to_name``. @@ -118,7 +120,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Error` **add_animation**\ (\ name\: :ref:`StringName`, animation\: :ref:`Animation`\ ) +:ref:`Error` **add_animation**\ (\ name\: :ref:`StringName`, animation\: :ref:`Animation`\ ) :ref:`🔗` Adds the ``animation`` to the library, accessible by the key ``name``. @@ -130,7 +132,7 @@ Adds the ``animation`` to the library, accessible by the key ``name``. .. rst-class:: classref-method -:ref:`Animation` **get_animation**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`Animation` **get_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the :ref:`Animation` with the key ``name``. If the animation does not exist, ``null`` is returned and an error is logged. @@ -142,7 +144,7 @@ Returns the :ref:`Animation` with the key ``name``. If the anim .. rst-class:: classref-method -:ref:`Array`\[:ref:`StringName`\] **get_animation_list**\ (\ ) |const| +:ref:`Array`\[:ref:`StringName`\] **get_animation_list**\ (\ ) |const| :ref:`🔗` Returns the keys for the :ref:`Animation`\ s stored in the library. @@ -150,11 +152,23 @@ Returns the keys for the :ref:`Animation`\ s stored in the libr ---- +.. _class_AnimationLibrary_method_get_animation_list_size: + +.. rst-class:: classref-method + +:ref:`int` **get_animation_list_size**\ (\ ) |const| :ref:`🔗` + +Returns the key count for the :ref:`Animation`\ s stored in the library. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationLibrary_method_has_animation: .. rst-class:: classref-method -:ref:`bool` **has_animation**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`bool` **has_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns ``true`` if the library stores an :ref:`Animation` with ``name`` as the key. @@ -166,7 +180,7 @@ Returns ``true`` if the library stores an :ref:`Animation` with .. rst-class:: classref-method -|void| **remove_animation**\ (\ name\: :ref:`StringName`\ ) +|void| **remove_animation**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Removes the :ref:`Animation` with the key ``name``. @@ -178,11 +192,12 @@ Removes the :ref:`Animation` with the key ``name``. .. rst-class:: classref-method -|void| **rename_animation**\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) +|void| **rename_animation**\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) :ref:`🔗` Changes the key of the :ref:`Animation` associated with the key ``name`` to ``newname``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationmixer.rst b/classes/class_animationmixer.rst index 11bd9505e9a..d33265e7cc8 100644 --- a/classes/class_animationmixer.rst +++ b/classes/class_animationmixer.rst @@ -25,6 +25,13 @@ Base class for :ref:`AnimationPlayer` and :ref:`Animation After instantiating the playback information data within the extended class, the blending is processed by the **AnimationMixer**. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Migrating Animations from Godot 4.0 to 4.3 `__ + .. rst-class:: classref-reftable-group Properties @@ -38,7 +45,7 @@ Properties +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`int` | :ref:`audio_max_polyphony` | ``32`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ - | :ref:`AnimationCallbackModeDiscrete` | :ref:`callback_mode_discrete` | ``0`` | + | :ref:`AnimationCallbackModeDiscrete` | :ref:`callback_mode_discrete` | ``1`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`AnimationCallbackModeMethod` | :ref:`callback_mode_method` | ``0`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ @@ -48,6 +55,8 @@ Properties +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`bool` | :ref:`reset_on_save` | ``true`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`root_motion_local` | ``false`` | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`NodePath` | :ref:`root_motion_track` | ``NodePath("")`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`NodePath` | :ref:`root_node` | ``NodePath("..")`` | @@ -118,7 +127,7 @@ Signals .. rst-class:: classref-signal -**animation_finished**\ (\ anim_name\: :ref:`StringName`\ ) +**animation_finished**\ (\ anim_name\: :ref:`StringName`\ ) :ref:`🔗` Notifies when an animation finished playing. @@ -132,7 +141,7 @@ Notifies when an animation finished playing. .. rst-class:: classref-signal -**animation_libraries_updated**\ (\ ) +**animation_libraries_updated**\ (\ ) :ref:`🔗` Notifies when the animation libraries have changed. @@ -144,7 +153,7 @@ Notifies when the animation libraries have changed. .. rst-class:: classref-signal -**animation_list_changed**\ (\ ) +**animation_list_changed**\ (\ ) :ref:`🔗` Notifies when an animation list is changed. @@ -156,10 +165,12 @@ Notifies when an animation list is changed. .. rst-class:: classref-signal -**animation_started**\ (\ anim_name\: :ref:`StringName`\ ) +**animation_started**\ (\ anim_name\: :ref:`StringName`\ ) :ref:`🔗` Notifies when an animation starts playing. +\ **Note:** This signal is not emitted if an animation is looping. + .. rst-class:: classref-item-separator ---- @@ -168,9 +179,21 @@ Notifies when an animation starts playing. .. rst-class:: classref-signal -**caches_cleared**\ (\ ) +**caches_cleared**\ (\ ) :ref:`🔗` + +Notifies when the caches have been cleared, either automatically, or manually via :ref:`clear_caches()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationMixer_signal_mixer_applied: + +.. rst-class:: classref-signal + +**mixer_applied**\ (\ ) :ref:`🔗` -Notifies when the caches have been cleared, either automatically, or manually via :ref:`clear_caches`. +Notifies when the blending result related have been applied to the target objects. .. rst-class:: classref-item-separator @@ -180,9 +203,9 @@ Notifies when the caches have been cleared, either automatically, or manually vi .. rst-class:: classref-signal -**mixer_updated**\ (\ ) +**mixer_updated**\ (\ ) :ref:`🔗` -Editor only. Notifies when the property have been updated to update dummy :ref:`AnimationPlayer` in animation player editor. +Notifies when the property related process have been updated. .. rst-class:: classref-section-separator @@ -197,7 +220,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **AnimationCallbackModeProcess**: +enum **AnimationCallbackModeProcess**: :ref:`🔗` .. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS: @@ -221,7 +244,7 @@ Process animation during process frames (see :ref:`Node.NOTIFICATION_INTERNAL_PR :ref:`AnimationCallbackModeProcess` **ANIMATION_CALLBACK_MODE_PROCESS_MANUAL** = ``2`` -Do not process animation. Use :ref:`advance` to process the animation manually. +Do not process animation. Use :ref:`advance()` to process the animation manually. .. rst-class:: classref-item-separator @@ -231,7 +254,7 @@ Do not process animation. Use :ref:`advance .. rst-class:: classref-enumeration -enum **AnimationCallbackModeMethod**: +enum **AnimationCallbackModeMethod**: :ref:`🔗` .. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_METHOD_DEFERRED: @@ -257,7 +280,7 @@ Make method calls immediately when reached in the animation. .. rst-class:: classref-enumeration -enum **AnimationCallbackModeDiscrete**: +enum **AnimationCallbackModeDiscrete**: :ref:`🔗` .. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT: @@ -265,9 +288,7 @@ enum **AnimationCallbackModeDiscrete**: :ref:`AnimationCallbackModeDiscrete` **ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT** = ``0`` -An :ref:`Animation.UPDATE_DISCRETE` track value takes precedence when blending :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track values and :ref:`Animation.UPDATE_DISCRETE` track values. This is the default behavior for :ref:`AnimationPlayer`. - -\ **Note:** If a value track has non-numeric type key values, it is internally converted to use :ref:`ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT` with :ref:`Animation.UPDATE_DISCRETE`. +An :ref:`Animation.UPDATE_DISCRETE` track value takes precedence when blending :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track values and :ref:`Animation.UPDATE_DISCRETE` track values. .. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE: @@ -275,7 +296,7 @@ An :ref:`Animation.UPDATE_DISCRETE` tr :ref:`AnimationCallbackModeDiscrete` **ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE** = ``1`` -An :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track value takes precedence when blending the :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track values and the :ref:`Animation.UPDATE_DISCRETE` track values. +An :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track value takes precedence when blending the :ref:`Animation.UPDATE_CONTINUOUS` or :ref:`Animation.UPDATE_CAPTURE` track values and the :ref:`Animation.UPDATE_DISCRETE` track values. This is the default behavior for :ref:`AnimationPlayer`. .. _class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS: @@ -285,6 +306,32 @@ An :ref:`Animation.UPDATE_CONTINUOUS Always treat the :ref:`Animation.UPDATE_DISCRETE` track value as :ref:`Animation.UPDATE_CONTINUOUS` with :ref:`Animation.INTERPOLATION_NEAREST`. This is the default behavior for :ref:`AnimationTree`. +If a value track has un-interpolatable type key values, it is internally converted to use :ref:`ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE` with :ref:`Animation.UPDATE_DISCRETE`. + +Un-interpolatable type list: + +- :ref:`@GlobalScope.TYPE_NIL`\ + +- :ref:`@GlobalScope.TYPE_NODE_PATH`\ + +- :ref:`@GlobalScope.TYPE_RID`\ + +- :ref:`@GlobalScope.TYPE_OBJECT`\ + +- :ref:`@GlobalScope.TYPE_CALLABLE`\ + +- :ref:`@GlobalScope.TYPE_SIGNAL`\ + +- :ref:`@GlobalScope.TYPE_DICTIONARY`\ + +- :ref:`@GlobalScope.TYPE_PACKED_BYTE_ARRAY`\ + +\ :ref:`@GlobalScope.TYPE_BOOL` and :ref:`@GlobalScope.TYPE_INT` are treated as :ref:`@GlobalScope.TYPE_FLOAT` during blending and rounded when the result is retrieved. + +It is same for arrays and vectors with them such as :ref:`@GlobalScope.TYPE_PACKED_INT32_ARRAY` or :ref:`@GlobalScope.TYPE_VECTOR2I`, they are treated as :ref:`@GlobalScope.TYPE_PACKED_FLOAT32_ARRAY` or :ref:`@GlobalScope.TYPE_VECTOR2`. Also note that for arrays, the size is also interpolated. + +\ :ref:`@GlobalScope.TYPE_STRING` and :ref:`@GlobalScope.TYPE_STRING_NAME` are interpolated between character codes and lengths, but note that there is a difference in algorithm between interpolation between keys and interpolation by blending. + .. rst-class:: classref-section-separator ---- @@ -298,7 +345,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **active** = ``true`` +:ref:`bool` **active** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -315,7 +362,7 @@ If ``true``, the **AnimationMixer** will be processing. .. rst-class:: classref-property -:ref:`int` **audio_max_polyphony** = ``32`` +:ref:`int` **audio_max_polyphony** = ``32`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -334,7 +381,7 @@ For example, if this value is ``32`` and the animation has two audio tracks, the .. rst-class:: classref-property -:ref:`AnimationCallbackModeDiscrete` **callback_mode_discrete** = ``0`` +:ref:`AnimationCallbackModeDiscrete` **callback_mode_discrete** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -355,7 +402,7 @@ To make the blended results look good, it is recommended to set this to :ref:`AN .. rst-class:: classref-property -:ref:`AnimationCallbackModeMethod` **callback_mode_method** = ``0`` +:ref:`AnimationCallbackModeMethod` **callback_mode_method** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -372,7 +419,7 @@ The call mode used for "Call Method" tracks. .. rst-class:: classref-property -:ref:`AnimationCallbackModeProcess` **callback_mode_process** = ``1`` +:ref:`AnimationCallbackModeProcess` **callback_mode_process** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -389,7 +436,7 @@ The process notification in which to update animations. .. rst-class:: classref-property -:ref:`bool` **deterministic** = ``false`` +:ref:`bool` **deterministic** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -416,7 +463,7 @@ For example, if :ref:`AnimationNodeAdd2` blends two nod .. rst-class:: classref-property -:ref:`bool` **reset_on_save** = ``true`` +:ref:`bool` **reset_on_save** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -431,20 +478,37 @@ This makes it more convenient to preview and edit animations in the editor, as c ---- +.. _class_AnimationMixer_property_root_motion_local: + +.. rst-class:: classref-property + +:ref:`bool` **root_motion_local** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_root_motion_local**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_root_motion_local**\ (\ ) + +If ``true``, :ref:`get_root_motion_position()` value is extracted as a local translation value before blending. In other words, it is treated like the translation is done after the rotation. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationMixer_property_root_motion_track: .. rst-class:: classref-property -:ref:`NodePath` **root_motion_track** = ``NodePath("")`` +:ref:`NodePath` **root_motion_track** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_root_motion_track**\ (\ value\: :ref:`NodePath`\ ) - :ref:`NodePath` **get_root_motion_track**\ (\ ) -The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. To specify a track that controls properties or bones, append its name after the path, separated by ``":"``. For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local"``. +The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. The :ref:`root_motion_track` uses the same format as :ref:`Animation.track_set_path()`, but note that a bone must be specified. -If the track has type :ref:`Animation.TYPE_POSITION_3D`, :ref:`Animation.TYPE_ROTATION_3D` or :ref:`Animation.TYPE_SCALE_3D` the transformation will be canceled visually, and the animation will appear to stay in place. See also :ref:`get_root_motion_position`, :ref:`get_root_motion_rotation`, :ref:`get_root_motion_scale` and :ref:`RootMotionView`. +If the track has type :ref:`Animation.TYPE_POSITION_3D`, :ref:`Animation.TYPE_ROTATION_3D`, or :ref:`Animation.TYPE_SCALE_3D` the transformation will be canceled visually, and the animation will appear to stay in place. See also :ref:`get_root_motion_position()`, :ref:`get_root_motion_rotation()`, :ref:`get_root_motion_scale()`, and :ref:`RootMotionView`. .. rst-class:: classref-item-separator @@ -454,7 +518,7 @@ If the track has type :ref:`Animation.TYPE_POSITION_3D` **root_node** = ``NodePath("..")`` +:ref:`NodePath` **root_node** = ``NodePath("..")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -476,7 +540,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Variant` **_post_process_key_value**\ (\ animation\: :ref:`Animation`, track\: :ref:`int`, value\: :ref:`Variant`, object_id\: :ref:`int`, object_sub_idx\: :ref:`int`\ ) |virtual| |const| +:ref:`Variant` **_post_process_key_value**\ (\ animation\: :ref:`Animation`, track\: :ref:`int`, value\: :ref:`Variant`, object_id\: :ref:`int`, object_sub_idx\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` A virtual function for processing after getting a key during playback. @@ -488,10 +552,22 @@ A virtual function for processing after getting a key during playback. .. rst-class:: classref-method -:ref:`Error` **add_animation_library**\ (\ name\: :ref:`StringName`, library\: :ref:`AnimationLibrary`\ ) +:ref:`Error` **add_animation_library**\ (\ name\: :ref:`StringName`, library\: :ref:`AnimationLibrary`\ ) :ref:`🔗` Adds ``library`` to the animation player, under the key ``name``. +AnimationMixer has a global library by default with an empty string as key. For adding an animation to the global library: + + +.. tabs:: + + .. code-tab:: gdscript + + var global_library = mixer.get_animation_library("") + global_library.add_animation("animation_name", animation_resource) + + + .. rst-class:: classref-item-separator ---- @@ -500,7 +576,7 @@ Adds ``library`` to the animation player, under the key ``name``. .. rst-class:: classref-method -|void| **advance**\ (\ delta\: :ref:`float`\ ) +|void| **advance**\ (\ delta\: :ref:`float`\ ) :ref:`🔗` Manually advance the animations by the specified time (in seconds). @@ -512,7 +588,7 @@ Manually advance the animations by the specified time (in seconds). .. rst-class:: classref-method -|void| **capture**\ (\ name\: :ref:`StringName`, duration\: :ref:`float`, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) +|void| **capture**\ (\ name\: :ref:`StringName`, duration\: :ref:`float`, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) :ref:`🔗` If the animation track specified by ``name`` has an option :ref:`Animation.UPDATE_CAPTURE`, stores current values of the objects indicated by the track path as a cache. If there is already a captured cache, the old cache is discarded. @@ -528,9 +604,9 @@ You can specify ``trans_type`` as the curve for the interpolation. For better re .. rst-class:: classref-method -|void| **clear_caches**\ (\ ) +|void| **clear_caches**\ (\ ) :ref:`🔗` -**AnimationMixer** caches animated nodes. It may not notice if a node disappears; :ref:`clear_caches` forces it to update the cache again. +**AnimationMixer** caches animated nodes. It may not notice if a node disappears; :ref:`clear_caches()` forces it to update the cache again. .. rst-class:: classref-item-separator @@ -540,7 +616,7 @@ You can specify ``trans_type`` as the curve for the interpolation. For better re .. rst-class:: classref-method -:ref:`StringName` **find_animation**\ (\ animation\: :ref:`Animation`\ ) |const| +:ref:`StringName` **find_animation**\ (\ animation\: :ref:`Animation`\ ) |const| :ref:`🔗` Returns the key of ``animation`` or an empty :ref:`StringName` if not found. @@ -552,7 +628,7 @@ Returns the key of ``animation`` or an empty :ref:`StringName` .. rst-class:: classref-method -:ref:`StringName` **find_animation_library**\ (\ animation\: :ref:`Animation`\ ) |const| +:ref:`StringName` **find_animation_library**\ (\ animation\: :ref:`Animation`\ ) |const| :ref:`🔗` Returns the key for the :ref:`AnimationLibrary` that contains ``animation`` or an empty :ref:`StringName` if not found. @@ -564,7 +640,7 @@ Returns the key for the :ref:`AnimationLibrary` that con .. rst-class:: classref-method -:ref:`Animation` **get_animation**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`Animation` **get_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the :ref:`Animation` with the key ``name``. If the animation does not exist, ``null`` is returned and an error is logged. @@ -576,11 +652,11 @@ Returns the :ref:`Animation` with the key ``name``. If the anim .. rst-class:: classref-method -:ref:`AnimationLibrary` **get_animation_library**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`AnimationLibrary` **get_animation_library**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the first :ref:`AnimationLibrary` with key ``name`` or ``null`` if not found. -To get the :ref:`AnimationPlayer`'s global animation library, use ``get_animation_library("")``. +To get the **AnimationMixer**'s global animation library, use ``get_animation_library("")``. .. rst-class:: classref-item-separator @@ -590,7 +666,7 @@ To get the :ref:`AnimationPlayer`'s global animation libr .. rst-class:: classref-method -:ref:`Array`\[:ref:`StringName`\] **get_animation_library_list**\ (\ ) |const| +:ref:`Array`\[:ref:`StringName`\] **get_animation_library_list**\ (\ ) |const| :ref:`🔗` Returns the list of stored library keys. @@ -602,7 +678,7 @@ Returns the list of stored library keys. .. rst-class:: classref-method -:ref:`PackedStringArray` **get_animation_list**\ (\ ) |const| +:ref:`PackedStringArray` **get_animation_list**\ (\ ) |const| :ref:`🔗` Returns the list of stored animation keys. @@ -614,7 +690,7 @@ Returns the list of stored animation keys. .. rst-class:: classref-method -:ref:`Vector3` **get_root_motion_position**\ (\ ) |const| +:ref:`Vector3` **get_root_motion_position**\ (\ ) |const| :ref:`🔗` Retrieve the motion delta of position with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. @@ -629,19 +705,38 @@ The most basic example is applying position to :ref:`CharacterBody3D`, you can apply the root motion position more correctly to account for the rotation of the node. + + +.. tabs:: + + .. code-tab:: gdscript + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + var velocity = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta set_velocity(velocity) move_and_slide() -By using this in combination with :ref:`get_root_motion_position_accumulator`, you can apply the root motion position more correctly to account for the rotation of the node. +If :ref:`root_motion_local` is ``true``, returns the pre-multiplied translation value with the inverted rotation. + +In this case, the code can be written as follows: .. tabs:: @@ -652,7 +747,7 @@ By using this in combination with :ref:`get_root_motion_position_accumulator` **get_root_motion_position_accumulator**\ (\ ) |const| +:ref:`Vector3` **get_root_motion_position_accumulator**\ (\ ) |const| :ref:`🔗` Retrieve the blended value of the position tracks with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. @@ -679,13 +774,13 @@ For example, if an animation with only one key ``Vector3(0, 0, 0)`` is played in .. code-tab:: gdscript - var prev_root_motion_position_accumulator: Vector3 - + var prev_root_motion_position_accumulator + func _process(delta): if Input.is_action_just_pressed("animate"): state_machine.travel("Animate") - var current_root_motion_position_accumulator: Vector3 = animation_tree.get_root_motion_position_accumulator() - var difference: Vector3 = current_root_motion_position_accumulator - prev_root_motion_position_accumulator + var current_root_motion_position_accumulator = animation_tree.get_root_motion_position_accumulator() + var difference = current_root_motion_position_accumulator - prev_root_motion_position_accumulator prev_root_motion_position_accumulator = current_root_motion_position_accumulator transform.origin += difference @@ -701,7 +796,7 @@ However, if the animation loops, an unintended discrete change may occur, so thi .. rst-class:: classref-method -:ref:`Quaternion` **get_root_motion_rotation**\ (\ ) |const| +:ref:`Quaternion` **get_root_motion_rotation**\ (\ ) |const| :ref:`🔗` Retrieve the motion delta of rotation with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. @@ -731,11 +826,11 @@ The most basic example is applying rotation to :ref:`CharacterBody3D` **get_root_motion_rotation_accumulator**\ (\ ) |const| +:ref:`Quaternion` **get_root_motion_rotation_accumulator**\ (\ ) |const| :ref:`🔗` Retrieve the blended value of the rotation tracks with the :ref:`root_motion_track` as a :ref:`Quaternion` that can be used elsewhere. -This is necessary to apply the root motion position correctly, taking rotation into account. See also :ref:`get_root_motion_position`. +This is necessary to apply the root motion position correctly, taking rotation into account. See also :ref:`get_root_motion_position()`. Also, this is useful in cases where you want to respect the initial key values of the animation. @@ -746,15 +841,15 @@ For example, if an animation with only one key ``Quaternion(0, 0, 0, 1)`` is pla .. code-tab:: gdscript - var prev_root_motion_rotation_accumulator: Quaternion - + var prev_root_motion_rotation_accumulator + func _process(delta): if Input.is_action_just_pressed("animate"): state_machine.travel("Animate") - var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_Quaternion_accumulator() - var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator + var current_root_motion_rotation_accumulator = animation_tree.get_root_motion_rotation_accumulator() + var difference = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator - transform.basis *= difference + transform.basis *= Basis(difference) @@ -768,7 +863,7 @@ However, if the animation loops, an unintended discrete change may occur, so thi .. rst-class:: classref-method -:ref:`Vector3` **get_root_motion_scale**\ (\ ) |const| +:ref:`Vector3` **get_root_motion_scale**\ (\ ) |const| :ref:`🔗` Retrieve the motion delta of scale with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. @@ -783,9 +878,9 @@ The most basic example is applying scale to :ref:`CharacterBody3D` **get_root_motion_scale_accumulator**\ (\ ) |const| +:ref:`Vector3` **get_root_motion_scale_accumulator**\ (\ ) |const| :ref:`🔗` Retrieve the blended value of the scale tracks with the :ref:`root_motion_track` as a :ref:`Vector3` that can be used elsewhere. @@ -815,13 +910,13 @@ For example, if an animation with only one key ``Vector3(1, 1, 1)`` is played in .. code-tab:: gdscript - var prev_root_motion_scale_accumulator: Vector3 - + var prev_root_motion_scale_accumulator + func _process(delta): if Input.is_action_just_pressed("animate"): state_machine.travel("Animate") - var current_root_motion_scale_accumulator: Vector3 = animation_tree.get_root_motion_scale_accumulator() - var difference: Vector3 = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator + var current_root_motion_scale_accumulator = animation_tree.get_root_motion_scale_accumulator() + var difference = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator transform.basis = transform.basis.scaled(difference) @@ -837,9 +932,9 @@ However, if the animation loops, an unintended discrete change may occur, so thi .. rst-class:: classref-method -:ref:`bool` **has_animation**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`bool` **has_animation**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns ``true`` if the :ref:`AnimationPlayer` stores an :ref:`Animation` with key ``name``. +Returns ``true`` if the **AnimationMixer** stores an :ref:`Animation` with key ``name``. .. rst-class:: classref-item-separator @@ -849,9 +944,9 @@ Returns ``true`` if the :ref:`AnimationPlayer` stores an .. rst-class:: classref-method -:ref:`bool` **has_animation_library**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`bool` **has_animation_library**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` -Returns ``true`` if the :ref:`AnimationPlayer` stores an :ref:`AnimationLibrary` with key ``name``. +Returns ``true`` if the **AnimationMixer** stores an :ref:`AnimationLibrary` with key ``name``. .. rst-class:: classref-item-separator @@ -861,7 +956,7 @@ Returns ``true`` if the :ref:`AnimationPlayer` stores an .. rst-class:: classref-method -|void| **remove_animation_library**\ (\ name\: :ref:`StringName`\ ) +|void| **remove_animation_library**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Removes the :ref:`AnimationLibrary` associated with the key ``name``. @@ -873,11 +968,12 @@ Removes the :ref:`AnimationLibrary` associated with the .. rst-class:: classref-method -|void| **rename_animation_library**\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) +|void| **rename_animation_library**\ (\ name\: :ref:`StringName`, newname\: :ref:`StringName`\ ) :ref:`🔗` Moves the :ref:`AnimationLibrary` associated with the key ``name`` to the key ``newname``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnode.rst b/classes/class_animationnode.rst index 127f1558a6a..04bd61362a0 100644 --- a/classes/class_animationnode.rst +++ b/classes/class_animationnode.rst @@ -12,7 +12,7 @@ AnimationNode **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AnimationNodeOutput`, :ref:`AnimationNodeSync`, :ref:`AnimationNodeTimeScale`, :ref:`AnimationNodeTimeSeek`, :ref:`AnimationRootNode` +**Inherited By:** :ref:`AnimationNodeExtension`, :ref:`AnimationNodeOutput`, :ref:`AnimationNodeSync`, :ref:`AnimationNodeTimeScale`, :ref:`AnimationNodeTimeSeek`, :ref:`AnimationRootNode` Base class for :ref:`AnimationTree` nodes. Not related to scene nodes. @@ -25,6 +25,16 @@ Base resource for :ref:`AnimationTree` nodes. In general, i Inherit this when creating animation nodes mainly for use in :ref:`AnimationNodeBlendTree`, otherwise :ref:`AnimationRootNode` should be used instead. +You can access the time information as read-only parameter which is processed and stored in the previous frame for all nodes except :ref:`AnimationNodeOutput`. + +\ **Note:** If multiple inputs exist in the **AnimationNode**, which time information takes precedence depends on the type of **AnimationNode**. + +:: + + var current_length = $AnimationTree["parameters/AnimationNodeName/current_length"] + var current_position = $AnimationTree["parameters/AnimationNodeName/current_position"] + var current_delta = $AnimationTree["parameters/AnimationNodeName/current_delta"] + .. rst-class:: classref-introduction-group Tutorials @@ -67,7 +77,7 @@ Methods +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_is_parameter_read_only`\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_process`\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| |const| | + | :ref:`float` | :ref:`_process`\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`add_input`\ (\ name\: :ref:`String`\ ) | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -85,8 +95,12 @@ Methods +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_parameter`\ (\ name\: :ref:`StringName`\ ) |const| | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_processing_animation_tree_instance_id`\ (\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_path_filtered`\ (\ path\: :ref:`NodePath`\ ) |const| | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_process_testing`\ (\ ) |const| | + +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_input`\ (\ index\: :ref:`int`\ ) | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_filter_path`\ (\ path\: :ref:`NodePath`, enable\: :ref:`bool`\ ) | @@ -109,7 +123,7 @@ Signals .. rst-class:: classref-signal -**animation_node_removed**\ (\ object_id\: :ref:`int`, name\: :ref:`String`\ ) +**animation_node_removed**\ (\ object_id\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` 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`. @@ -121,7 +135,7 @@ Emitted by nodes that inherit from this class and that have an internal tree whe .. rst-class:: classref-signal -**animation_node_renamed**\ (\ object_id\: :ref:`int`, old_name\: :ref:`String`, new_name\: :ref:`String`\ ) +**animation_node_renamed**\ (\ object_id\: :ref:`int`, old_name\: :ref:`String`, new_name\: :ref:`String`\ ) :ref:`🔗` 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`. @@ -133,7 +147,7 @@ Emitted by nodes that inherit from this class and that have an internal tree whe .. rst-class:: classref-signal -**tree_changed**\ (\ ) +**tree_changed**\ (\ ) :ref:`🔗` 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`. @@ -150,7 +164,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FilterAction**: +enum **FilterAction**: :ref:`🔗` .. _class_AnimationNode_constant_FILTER_IGNORE: @@ -197,7 +211,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **filter_enabled** +:ref:`bool` **filter_enabled** :ref:`🔗` .. rst-class:: classref-property-setget @@ -219,7 +233,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`String` **_get_caption**\ (\ ) |virtual| |const| +:ref:`String` **_get_caption**\ (\ ) |virtual| |const| :ref:`🔗` When inheriting from :ref:`AnimationRootNode`, implement this virtual method to override the text caption for this animation node. @@ -231,7 +245,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`AnimationNode` **_get_child_by_name**\ (\ name\: :ref:`StringName`\ ) |virtual| |const| +:ref:`AnimationNode` **_get_child_by_name**\ (\ name\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return a child animation node by its ``name``. @@ -243,7 +257,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`Dictionary` **_get_child_nodes**\ (\ ) |virtual| |const| +:ref:`Dictionary` **_get_child_nodes**\ (\ ) |virtual| |const| :ref:`🔗` When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return all child animation nodes in order as a ``name: node`` dictionary. @@ -255,7 +269,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`Variant` **_get_parameter_default_value**\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| +:ref:`Variant` **_get_parameter_default_value**\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` 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. @@ -267,9 +281,9 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`Array` **_get_parameter_list**\ (\ ) |virtual| |const| +:ref:`Array` **_get_parameter_list**\ (\ ) |virtual| |const| :ref:`🔗` -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`. +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 @@ -279,7 +293,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`bool` **_has_filter**\ (\ ) |virtual| |const| +:ref:`bool` **_has_filter**\ (\ ) |virtual| |const| :ref:`🔗` When inheriting from :ref:`AnimationRootNode`, implement this virtual method to return whether the blend tree editor should display filter editing on this animation node. @@ -291,7 +305,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`bool` **_is_parameter_read_only**\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| +:ref:`bool` **_is_parameter_read_only**\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` 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. @@ -303,13 +317,15 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`float` **_process**\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| |const| +:ref:`float` **_process**\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| :ref:`🔗` + +**Deprecated:** Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future. 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. +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. -This function should return the time left for the current animation to finish (if unsure, pass the value from the main blend being called). +This function should return the delta. .. rst-class:: classref-item-separator @@ -319,7 +335,7 @@ This function should return the time left for the current animation to finish (i .. rst-class:: classref-method -:ref:`bool` **add_input**\ (\ name\: :ref:`String`\ ) +:ref:`bool` **add_input**\ (\ name\: :ref:`String`\ ) :ref:`🔗` 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``. @@ -331,11 +347,11 @@ Adds an input to the animation node. This is only useful for animation nodes cre .. rst-class:: classref-method -|void| **blend_animation**\ (\ animation\: :ref:`StringName`, time\: :ref:`float`, delta\: :ref:`float`, seeked\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, looped_flag\: :ref:`LoopedFlag` = 0\ ) +|void| **blend_animation**\ (\ animation\: :ref:`StringName`, time\: :ref:`float`, delta\: :ref:`float`, seeked\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, looped_flag\: :ref:`LoopedFlag` = 0\ ) :ref:`🔗` -Blend an animation by ``blend`` amount (name must be valid in the linked :ref:`AnimationPlayer`). A ``time`` and ``delta`` may be passed, as well as whether ``seeked`` happened. +Blends an animation by ``blend`` amount (name must be valid in the linked :ref:`AnimationPlayer`). A ``time`` and ``delta`` may be passed, as well as whether ``seeked`` happened. -A ``looped_flag`` is used by internal processing immediately after the loop. See also :ref:`LoopedFlag`. +A ``looped_flag`` is used by internal processing immediately after the loop. .. rst-class:: classref-item-separator @@ -345,9 +361,9 @@ A ``looped_flag`` is used by internal processing immediately after the loop. See .. rst-class:: classref-method -:ref:`float` **blend_input**\ (\ input_index\: :ref:`int`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) +:ref:`float` **blend_input**\ (\ input_index\: :ref:`int`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) :ref:`🔗` -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). +Blends 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. .. rst-class:: classref-item-separator @@ -357,7 +373,7 @@ Blend an input. This is only useful for animation nodes created for an :ref:`Ani .. rst-class:: classref-method -:ref:`float` **blend_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) +:ref:`float` **blend_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, blend\: :ref:`float`, filter\: :ref:`FilterAction` = 0, sync\: :ref:`bool` = true, test_only\: :ref:`bool` = false\ ) :ref:`🔗` Blend another animation node (in case this animation node contains child animation nodes). This function is only useful if you inherit from :ref:`AnimationRootNode` instead, otherwise editors will not display your animation node for addition. @@ -369,7 +385,7 @@ Blend another animation node (in case this animation node contains child animati .. rst-class:: classref-method -:ref:`int` **find_input**\ (\ name\: :ref:`String`\ ) |const| +:ref:`int` **find_input**\ (\ name\: :ref:`String`\ ) |const| :ref:`🔗` Returns the input index which corresponds to ``name``. If not found, returns ``-1``. @@ -381,7 +397,7 @@ Returns the input index which corresponds to ``name``. If not found, returns ``- .. rst-class:: classref-method -:ref:`int` **get_input_count**\ (\ ) |const| +:ref:`int` **get_input_count**\ (\ ) |const| :ref:`🔗` Amount of inputs in this animation node, only useful for animation nodes that go into :ref:`AnimationNodeBlendTree`. @@ -393,7 +409,7 @@ Amount of inputs in this animation node, only useful for animation nodes that go .. rst-class:: classref-method -:ref:`String` **get_input_name**\ (\ input\: :ref:`int`\ ) |const| +:ref:`String` **get_input_name**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` Gets the name of an input by index. @@ -405,7 +421,7 @@ Gets the name of an input by index. .. rst-class:: classref-method -:ref:`Variant` **get_parameter**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`Variant` **get_parameter**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` 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. @@ -413,13 +429,39 @@ Gets the value of a parameter. Parameters are custom local memory used for your ---- +.. _class_AnimationNode_method_get_processing_animation_tree_instance_id: + +.. rst-class:: classref-method + +:ref:`int` **get_processing_animation_tree_instance_id**\ (\ ) |const| :ref:`🔗` + +Returns the object id of the :ref:`AnimationTree` that owns this node. + +\ **Note:** This method should only be called from within the :ref:`AnimationNodeExtension._process_animation_node()` method, and will return an invalid id otherwise. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNode_method_is_path_filtered: .. rst-class:: classref-method -:ref:`bool` **is_path_filtered**\ (\ path\: :ref:`NodePath`\ ) |const| +:ref:`bool` **is_path_filtered**\ (\ path\: :ref:`NodePath`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given path is filtered. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNode_method_is_process_testing: + +.. rst-class:: classref-method + +:ref:`bool` **is_process_testing**\ (\ ) |const| :ref:`🔗` -Returns whether the given path is filtered. +Returns ``true`` if this animation node is being processed in test-only mode. .. rst-class:: classref-item-separator @@ -429,7 +471,7 @@ Returns whether the given path is filtered. .. rst-class:: classref-method -|void| **remove_input**\ (\ index\: :ref:`int`\ ) +|void| **remove_input**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Removes an input, call this only when inactive. @@ -441,7 +483,7 @@ Removes an input, call this only when inactive. .. rst-class:: classref-method -|void| **set_filter_path**\ (\ path\: :ref:`NodePath`, enable\: :ref:`bool`\ ) +|void| **set_filter_path**\ (\ path\: :ref:`NodePath`, enable\: :ref:`bool`\ ) :ref:`🔗` Adds or removes a path for the filter. @@ -453,7 +495,7 @@ Adds or removes a path for the filter. .. rst-class:: classref-method -:ref:`bool` **set_input_name**\ (\ input\: :ref:`int`, name\: :ref:`String`\ ) +:ref:`bool` **set_input_name**\ (\ input\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` Sets the name of the input at the given ``input`` index. If the setting fails, returns ``false``. @@ -465,11 +507,12 @@ Sets the name of the input at the given ``input`` index. If the setting fails, r .. rst-class:: classref-method -|void| **set_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) +|void| **set_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) :ref:`🔗` Sets a custom parameter. These are used as local memory, because resources can be reused across the tree or scenes. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeadd2.rst b/classes/class_animationnodeadd2.rst index c23b86a53bb..4b4a283653c 100644 --- a/classes/class_animationnodeadd2.rst +++ b/classes/class_animationnodeadd2.rst @@ -33,6 +33,7 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeadd3.rst b/classes/class_animationnodeadd3.rst index 313bd91232c..05c5c9c05f3 100644 --- a/classes/class_animationnodeadd3.rst +++ b/classes/class_animationnodeadd3.rst @@ -38,9 +38,10 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeanimation.rst b/classes/class_animationnodeanimation.rst index 46cee9bf212..e0fa3591ccb 100644 --- a/classes/class_animationnodeanimation.rst +++ b/classes/class_animationnodeanimation.rst @@ -28,9 +28,9 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -40,11 +40,23 @@ Properties .. table:: :widths: auto - +-------------------------------------------------------+-------------------------------------------------------------------+---------+ - | :ref:`StringName` | :ref:`animation` | ``&""`` | - +-------------------------------------------------------+-------------------------------------------------------------------+---------+ - | :ref:`PlayMode` | :ref:`play_mode` | ``0`` | - +-------------------------------------------------------+-------------------------------------------------------------------+---------+ + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`advance_on_start` | ``false`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`animation` | ``&""`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`LoopMode` | :ref:`loop_mode` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`PlayMode` | :ref:`play_mode` | ``0`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`start_offset` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`stretch_time_scale` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`timeline_length` | | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`use_custom_timeline` | ``false`` | + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-section-separator @@ -59,7 +71,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **PlayMode**: +enum **PlayMode**: :ref:`🔗` .. _class_AnimationNodeAnimation_constant_PLAY_MODE_FORWARD: @@ -86,11 +98,30 @@ Plays animation in backward direction. Property Descriptions --------------------- +.. _class_AnimationNodeAnimation_property_advance_on_start: + +.. rst-class:: classref-property + +:ref:`bool` **advance_on_start** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_advance_on_start**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_advance_on_start**\ (\ ) + +If ``true``, on receiving a request to play an animation from the start, the first frame is not drawn, but only processed, and playback starts from the next frame. + +See also the notes of :ref:`AnimationPlayer.play()`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeAnimation_property_animation: .. rst-class:: classref-property -:ref:`StringName` **animation** = ``&""`` +:ref:`StringName` **animation** = ``&""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -103,11 +134,30 @@ Animation to use as an output. It is one of the animations provided by :ref:`Ani ---- +.. _class_AnimationNodeAnimation_property_loop_mode: + +.. rst-class:: classref-property + +:ref:`LoopMode` **loop_mode** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) +- :ref:`LoopMode` **get_loop_mode**\ (\ ) + +If :ref:`use_custom_timeline` is ``true``, override the loop settings of the original :ref:`Animation` resource with the value. + +\ **Note:** If the :ref:`Animation.loop_mode` isn't set to looping, the :ref:`Animation.track_set_interpolation_loop_wrap()` option will not be respected. If you cannot get the expected behavior, consider duplicating the :ref:`Animation` resource and changing the loop settings. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeAnimation_property_play_mode: .. rst-class:: classref-property -:ref:`PlayMode` **play_mode** = ``0`` +:ref:`PlayMode` **play_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -116,7 +166,82 @@ Animation to use as an output. It is one of the animations provided by :ref:`Ani Determines the playback direction of the animation. +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_start_offset: + +.. rst-class:: classref-property + +:ref:`float` **start_offset** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_start_offset**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_start_offset**\ (\ ) + +If :ref:`use_custom_timeline` is ``true``, offset the start position of the animation. + +This is useful for adjusting which foot steps first in 3D walking animations. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_stretch_time_scale: + +.. rst-class:: classref-property + +:ref:`bool` **stretch_time_scale** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stretch_time_scale**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_stretching_time_scale**\ (\ ) + +If ``true``, scales the time so that the length specified in :ref:`timeline_length` is one cycle. + +This is useful for matching the periods of walking and running animations. + +If ``false``, the original animation length is respected. If you set the loop to :ref:`loop_mode`, the animation will loop in :ref:`timeline_length`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_timeline_length: + +.. rst-class:: classref-property + +:ref:`float` **timeline_length** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_timeline_length**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_timeline_length**\ (\ ) + +If :ref:`use_custom_timeline` is ``true``, offset the start position of the animation. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeAnimation_property_use_custom_timeline: + +.. rst-class:: classref-property + +:ref:`bool` **use_custom_timeline** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_use_custom_timeline**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_using_custom_timeline**\ (\ ) + +If ``true``, :ref:`AnimationNode` provides an animation based on the :ref:`Animation` resource with some parameters adjusted. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeblend2.rst b/classes/class_animationnodeblend2.rst index ca333217cc3..4affaacd955 100644 --- a/classes/class_animationnodeblend2.rst +++ b/classes/class_animationnodeblend2.rst @@ -30,11 +30,12 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeblend3.rst b/classes/class_animationnodeblend3.rst index 4b7837d7e5a..c8f86ae6f73 100644 --- a/classes/class_animationnodeblend3.rst +++ b/classes/class_animationnodeblend3.rst @@ -39,6 +39,7 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeblendspace1d.rst b/classes/class_animationnodeblendspace1d.rst index 186eb60bd6c..85157dd62d3 100644 --- a/classes/class_animationnodeblendspace1d.rst +++ b/classes/class_animationnodeblendspace1d.rst @@ -21,7 +21,7 @@ Description A resource used by :ref:`AnimationNodeBlendTree`. -\ **AnimationNodeBlendSpace1D** represents a virtual axis on which any type of :ref:`AnimationRootNode`\ s can be added using :ref:`add_blend_point`. Outputs the linear blend of the two :ref:`AnimationRootNode`\ s adjacent to the current value. +\ **AnimationNodeBlendSpace1D** represents a virtual axis on which any type of :ref:`AnimationRootNode`\ s can be added using :ref:`add_blend_point()`. Outputs the linear blend of the two :ref:`AnimationRootNode`\ s adjacent to the current value. You can set the extents of the axis with :ref:`min_space` and :ref:`max_space`. @@ -91,7 +91,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **BlendMode**: +enum **BlendMode**: :ref:`🔗` .. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_INTERPOLATED: @@ -130,14 +130,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`BlendMode` **blend_mode** = ``0`` +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) - :ref:`BlendMode` **get_blend_mode**\ (\ ) -Controls the interpolation between animations. See :ref:`BlendMode` constants. +Controls the interpolation between animations. .. rst-class:: classref-item-separator @@ -147,14 +147,14 @@ Controls the interpolation between animations. See :ref:`BlendMode` **max_space** = ``1.0`` +:ref:`float` **max_space** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_max_space**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_max_space**\ (\ ) -The blend space's axis's upper limit for the points' position. See :ref:`add_blend_point`. +The blend space's axis's upper limit for the points' position. See :ref:`add_blend_point()`. .. rst-class:: classref-item-separator @@ -164,14 +164,14 @@ The blend space's axis's upper limit for the points' position. See :ref:`add_ble .. rst-class:: classref-property -:ref:`float` **min_space** = ``-1.0`` +:ref:`float` **min_space** = ``-1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_min_space**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_min_space**\ (\ ) -The blend space's axis's lower limit for the points' position. See :ref:`add_blend_point`. +The blend space's axis's lower limit for the points' position. See :ref:`add_blend_point()`. .. rst-class:: classref-item-separator @@ -181,7 +181,7 @@ The blend space's axis's lower limit for the points' position. See :ref:`add_ble .. rst-class:: classref-property -:ref:`float` **snap** = ``0.1`` +:ref:`float` **snap** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,7 +198,7 @@ Position increment to snap to when moving a point on the axis. .. rst-class:: classref-property -:ref:`bool` **sync** = ``false`` +:ref:`bool` **sync** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -217,7 +217,7 @@ If ``true``, forcing the blended animations to advance frame. .. rst-class:: classref-property -:ref:`String` **value_label** = ``"value"`` +:ref:`String` **value_label** = ``"value"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -239,7 +239,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`float`, at_index\: :ref:`int` = -1\ ) +|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`float`, at_index\: :ref:`int` = -1\ ) :ref:`🔗` Adds a new point that represents a ``node`` on the virtual axis at a given position set by ``pos``. You can insert it at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array. @@ -251,7 +251,7 @@ Adds a new point that represents a ``node`` on the virtual axis at a given posit .. rst-class:: classref-method -:ref:`int` **get_blend_point_count**\ (\ ) |const| +:ref:`int` **get_blend_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points on the blend axis. @@ -263,7 +263,7 @@ Returns the number of points on the blend axis. .. rst-class:: classref-method -:ref:`AnimationRootNode` **get_blend_point_node**\ (\ point\: :ref:`int`\ ) |const| +:ref:`AnimationRootNode` **get_blend_point_node**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the :ref:`AnimationNode` referenced by the point at index ``point``. @@ -275,7 +275,7 @@ Returns the :ref:`AnimationNode` referenced by the point at .. rst-class:: classref-method -:ref:`float` **get_blend_point_position**\ (\ point\: :ref:`int`\ ) |const| +:ref:`float` **get_blend_point_position**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point at index ``point``. @@ -287,7 +287,7 @@ Returns the position of the point at index ``point``. .. rst-class:: classref-method -|void| **remove_blend_point**\ (\ point\: :ref:`int`\ ) +|void| **remove_blend_point**\ (\ point\: :ref:`int`\ ) :ref:`🔗` Removes the point at index ``point`` from the blend axis. @@ -299,7 +299,7 @@ Removes the point at index ``point`` from the blend axis. .. rst-class:: classref-method -|void| **set_blend_point_node**\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) +|void| **set_blend_point_node**\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) :ref:`🔗` Changes the :ref:`AnimationNode` referenced by the point at index ``point``. @@ -311,11 +311,12 @@ Changes the :ref:`AnimationNode` referenced by the point at .. rst-class:: classref-method -|void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`float`\ ) +|void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`float`\ ) :ref:`🔗` Updates the position of the point at index ``point`` on the blend axis. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeblendspace2d.rst b/classes/class_animationnodeblendspace2d.rst index 285ec23541d..12bdec3c7de 100644 --- a/classes/class_animationnodeblendspace2d.rst +++ b/classes/class_animationnodeblendspace2d.rst @@ -21,9 +21,9 @@ Description A resource used by :ref:`AnimationNodeBlendTree`. -\ :ref:`AnimationNodeBlendSpace1D` represents a virtual 2D space on which :ref:`AnimationRootNode`\ s are placed. Outputs the linear blend of the three adjacent animations using a :ref:`Vector2` weight. Adjacent in this context means the three :ref:`AnimationRootNode`\ s making up the triangle that contains the current value. +\ **AnimationNodeBlendSpace2D** represents a virtual 2D space on which :ref:`AnimationRootNode`\ s are placed. Outputs the linear blend of the three adjacent animations using a :ref:`Vector2` weight. Adjacent in this context means the three :ref:`AnimationRootNode`\ s making up the triangle that contains the current value. -You can add vertices to the blend space with :ref:`add_blend_point` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle` and :ref:`remove_triangle` to triangulate the blend space by hand. +You can add vertices to the blend space with :ref:`add_blend_point()` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle()` and :ref:`remove_triangle()` to triangulate the blend space by hand. .. rst-class:: classref-introduction-group @@ -32,7 +32,7 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -105,7 +105,7 @@ Signals .. rst-class:: classref-signal -**triangles_updated**\ (\ ) +**triangles_updated**\ (\ ) :ref:`🔗` Emitted every time the blend space's triangles are created, removed, or when one of their vertices changes position. @@ -122,7 +122,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **BlendMode**: +enum **BlendMode**: :ref:`🔗` .. _class_AnimationNodeBlendSpace2D_constant_BLEND_MODE_INTERPOLATED: @@ -161,14 +161,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **auto_triangles** = ``true`` +:ref:`bool` **auto_triangles** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_triangles**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_auto_triangles**\ (\ ) -If ``true``, the blend space is triangulated automatically. The mesh updates every time you add or remove points with :ref:`add_blend_point` and :ref:`remove_blend_point`. +If ``true``, the blend space is triangulated automatically. The mesh updates every time you add or remove points with :ref:`add_blend_point()` and :ref:`remove_blend_point()`. .. rst-class:: classref-item-separator @@ -178,14 +178,14 @@ If ``true``, the blend space is triangulated automatically. The mesh updates eve .. rst-class:: classref-property -:ref:`BlendMode` **blend_mode** = ``0`` +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) - :ref:`BlendMode` **get_blend_mode**\ (\ ) -Controls the interpolation between animations. See :ref:`BlendMode` constants. +Controls the interpolation between animations. .. rst-class:: classref-item-separator @@ -195,14 +195,14 @@ Controls the interpolation between animations. See :ref:`BlendMode` **max_space** = ``Vector2(1, 1)`` +:ref:`Vector2` **max_space** = ``Vector2(1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_max_space**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_max_space**\ (\ ) -The blend space's X and Y axes' upper limit for the points' position. See :ref:`add_blend_point`. +The blend space's X and Y axes' upper limit for the points' position. See :ref:`add_blend_point()`. .. rst-class:: classref-item-separator @@ -212,14 +212,14 @@ The blend space's X and Y axes' upper limit for the points' position. See :ref:` .. rst-class:: classref-property -:ref:`Vector2` **min_space** = ``Vector2(-1, -1)`` +:ref:`Vector2` **min_space** = ``Vector2(-1, -1)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_min_space**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_min_space**\ (\ ) -The blend space's X and Y axes' lower limit for the points' position. See :ref:`add_blend_point`. +The blend space's X and Y axes' lower limit for the points' position. See :ref:`add_blend_point()`. .. rst-class:: classref-item-separator @@ -229,7 +229,7 @@ The blend space's X and Y axes' lower limit for the points' position. See :ref:` .. rst-class:: classref-property -:ref:`Vector2` **snap** = ``Vector2(0.1, 0.1)`` +:ref:`Vector2` **snap** = ``Vector2(0.1, 0.1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -246,7 +246,7 @@ Position increment to snap to when moving a point. .. rst-class:: classref-property -:ref:`bool` **sync** = ``false`` +:ref:`bool` **sync** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -265,7 +265,7 @@ If ``true``, forcing the blended animations to advance frame. .. rst-class:: classref-property -:ref:`String` **x_label** = ``"x"`` +:ref:`String` **x_label** = ``"x"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -282,7 +282,7 @@ Name of the blend space's X axis. .. rst-class:: classref-property -:ref:`String` **y_label** = ``"y"`` +:ref:`String` **y_label** = ``"y"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -304,7 +304,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`Vector2`, at_index\: :ref:`int` = -1\ ) +|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode`, pos\: :ref:`Vector2`, at_index\: :ref:`int` = -1\ ) :ref:`🔗` Adds a new point that represents a ``node`` at the position set by ``pos``. You can insert it at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array. @@ -316,7 +316,7 @@ Adds a new point that represents a ``node`` at the position set by ``pos``. You .. rst-class:: classref-method -|void| **add_triangle**\ (\ x\: :ref:`int`, y\: :ref:`int`, z\: :ref:`int`, at_index\: :ref:`int` = -1\ ) +|void| **add_triangle**\ (\ x\: :ref:`int`, y\: :ref:`int`, z\: :ref:`int`, at_index\: :ref:`int` = -1\ ) :ref:`🔗` Creates a new triangle using three points ``x``, ``y``, and ``z``. Triangles can overlap. You can insert the triangle at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array. @@ -328,7 +328,7 @@ Creates a new triangle using three points ``x``, ``y``, and ``z``. Triangles can .. rst-class:: classref-method -:ref:`int` **get_blend_point_count**\ (\ ) |const| +:ref:`int` **get_blend_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points in the blend space. @@ -340,7 +340,7 @@ Returns the number of points in the blend space. .. rst-class:: classref-method -:ref:`AnimationRootNode` **get_blend_point_node**\ (\ point\: :ref:`int`\ ) |const| +:ref:`AnimationRootNode` **get_blend_point_node**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the :ref:`AnimationRootNode` referenced by the point at index ``point``. @@ -352,7 +352,7 @@ Returns the :ref:`AnimationRootNode` referenced by the .. rst-class:: classref-method -:ref:`Vector2` **get_blend_point_position**\ (\ point\: :ref:`int`\ ) |const| +:ref:`Vector2` **get_blend_point_position**\ (\ point\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point at index ``point``. @@ -364,7 +364,7 @@ Returns the position of the point at index ``point``. .. rst-class:: classref-method -:ref:`int` **get_triangle_count**\ (\ ) |const| +:ref:`int` **get_triangle_count**\ (\ ) |const| :ref:`🔗` Returns the number of triangles in the blend space. @@ -376,7 +376,7 @@ Returns the number of triangles in the blend space. .. rst-class:: classref-method -:ref:`int` **get_triangle_point**\ (\ triangle\: :ref:`int`, point\: :ref:`int`\ ) +:ref:`int` **get_triangle_point**\ (\ triangle\: :ref:`int`, point\: :ref:`int`\ ) :ref:`🔗` Returns the position of the point at index ``point`` in the triangle of index ``triangle``. @@ -388,7 +388,7 @@ Returns the position of the point at index ``point`` in the triangle of index `` .. rst-class:: classref-method -|void| **remove_blend_point**\ (\ point\: :ref:`int`\ ) +|void| **remove_blend_point**\ (\ point\: :ref:`int`\ ) :ref:`🔗` Removes the point at index ``point`` from the blend space. @@ -400,7 +400,7 @@ Removes the point at index ``point`` from the blend space. .. rst-class:: classref-method -|void| **remove_triangle**\ (\ triangle\: :ref:`int`\ ) +|void| **remove_triangle**\ (\ triangle\: :ref:`int`\ ) :ref:`🔗` Removes the triangle at index ``triangle`` from the blend space. @@ -412,7 +412,7 @@ Removes the triangle at index ``triangle`` from the blend space. .. rst-class:: classref-method -|void| **set_blend_point_node**\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) +|void| **set_blend_point_node**\ (\ point\: :ref:`int`, node\: :ref:`AnimationRootNode`\ ) :ref:`🔗` Changes the :ref:`AnimationNode` referenced by the point at index ``point``. @@ -424,11 +424,12 @@ Changes the :ref:`AnimationNode` referenced by the point at .. rst-class:: classref-method -|void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`Vector2`\ ) +|void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`Vector2`\ ) :ref:`🔗` -Updates the position of the point at index ``point`` on the blend axis. +Updates the position of the point at index ``point`` in the blend space. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeblendtree.rst b/classes/class_animationnodeblendtree.rst index da7c6ca52b6..eb4c125b785 100644 --- a/classes/class_animationnodeblendtree.rst +++ b/classes/class_animationnodeblendtree.rst @@ -50,25 +50,27 @@ Methods .. table:: :widths: auto - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`add_node`\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`connect_node`\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`, output_node\: :ref:`StringName`\ ) | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`disconnect_node`\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`\ ) | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`AnimationNode` | :ref:`get_node`\ (\ name\: :ref:`StringName`\ ) |const| | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`get_node_position`\ (\ name\: :ref:`StringName`\ ) |const| | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`has_node`\ (\ name\: :ref:`StringName`\ ) |const| | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`remove_node`\ (\ name\: :ref:`StringName`\ ) | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`rename_node`\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_node_position`\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) | - +-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_node`\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`connect_node`\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`, output_node\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`disconnect_node`\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationNode` | :ref:`get_node`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_node_list`\ (\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_node_position`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_node`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_node`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`rename_node`\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_node_position`\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) | + +------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -83,7 +85,7 @@ Signals .. rst-class:: classref-signal -**node_changed**\ (\ node_name\: :ref:`StringName`\ ) +**node_changed**\ (\ node_name\: :ref:`StringName`\ ) :ref:`🔗` Emitted when the input port information is changed. @@ -100,7 +102,7 @@ Constants .. rst-class:: classref-constant -**CONNECTION_OK** = ``0`` +**CONNECTION_OK** = ``0`` :ref:`🔗` The connection was successful. @@ -108,7 +110,7 @@ The connection was successful. .. rst-class:: classref-constant -**CONNECTION_ERROR_NO_INPUT** = ``1`` +**CONNECTION_ERROR_NO_INPUT** = ``1`` :ref:`🔗` The input node is ``null``. @@ -116,7 +118,7 @@ The input node is ``null``. .. rst-class:: classref-constant -**CONNECTION_ERROR_NO_INPUT_INDEX** = ``2`` +**CONNECTION_ERROR_NO_INPUT_INDEX** = ``2`` :ref:`🔗` The specified input port is out of range. @@ -124,7 +126,7 @@ The specified input port is out of range. .. rst-class:: classref-constant -**CONNECTION_ERROR_NO_OUTPUT** = ``3`` +**CONNECTION_ERROR_NO_OUTPUT** = ``3`` :ref:`🔗` The output node is ``null``. @@ -132,7 +134,7 @@ The output node is ``null``. .. rst-class:: classref-constant -**CONNECTION_ERROR_SAME_NODE** = ``4`` +**CONNECTION_ERROR_SAME_NODE** = ``4`` :ref:`🔗` Input and output nodes are the same. @@ -140,7 +142,7 @@ Input and output nodes are the same. .. rst-class:: classref-constant -**CONNECTION_ERROR_CONNECTION_EXISTS** = ``5`` +**CONNECTION_ERROR_CONNECTION_EXISTS** = ``5`` :ref:`🔗` The specified connection already exists. @@ -157,7 +159,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Vector2` **graph_offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **graph_offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -179,7 +181,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) +|void| **add_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) :ref:`🔗` Adds an :ref:`AnimationNode` at the given ``position``. The ``name`` is used to identify the created sub animation node later. @@ -191,7 +193,7 @@ Adds an :ref:`AnimationNode` at the given ``position``. The .. rst-class:: classref-method -|void| **connect_node**\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`, output_node\: :ref:`StringName`\ ) +|void| **connect_node**\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`, output_node\: :ref:`StringName`\ ) :ref:`🔗` Connects the output of an :ref:`AnimationNode` as input for another :ref:`AnimationNode`, at the input port specified by ``input_index``. @@ -203,7 +205,7 @@ Connects the output of an :ref:`AnimationNode` as input for .. rst-class:: classref-method -|void| **disconnect_node**\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`\ ) +|void| **disconnect_node**\ (\ input_node\: :ref:`StringName`, input_index\: :ref:`int`\ ) :ref:`🔗` Disconnects the animation node connected to the specified input. @@ -215,7 +217,7 @@ Disconnects the animation node connected to the specified input. .. rst-class:: classref-method -:ref:`AnimationNode` **get_node**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`AnimationNode` **get_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the sub animation node with the specified ``name``. @@ -223,11 +225,23 @@ Returns the sub animation node with the specified ``name``. ---- +.. _class_AnimationNodeBlendTree_method_get_node_list: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`StringName`\] **get_node_list**\ (\ ) |const| :ref:`🔗` + +Returns a list containing the names of all sub animation nodes in this blend tree. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeBlendTree_method_get_node_position: .. rst-class:: classref-method -:ref:`Vector2` **get_node_position**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`Vector2` **get_node_position**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the position of the sub animation node with the specified ``name``. @@ -239,7 +253,7 @@ Returns the position of the sub animation node with the specified ``name``. .. rst-class:: classref-method -:ref:`bool` **has_node**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`bool` **has_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns ``true`` if a sub animation node with specified ``name`` exists. @@ -251,7 +265,7 @@ Returns ``true`` if a sub animation node with specified ``name`` exists. .. rst-class:: classref-method -|void| **remove_node**\ (\ name\: :ref:`StringName`\ ) +|void| **remove_node**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Removes a sub animation node. @@ -263,7 +277,7 @@ Removes a sub animation node. .. rst-class:: classref-method -|void| **rename_node**\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) +|void| **rename_node**\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` Changes the name of a sub animation node. @@ -275,11 +289,12 @@ Changes the name of a sub animation node. .. rst-class:: classref-method -|void| **set_node_position**\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) +|void| **set_node_position**\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) :ref:`🔗` 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.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeextension.rst b/classes/class_animationnodeextension.rst new file mode 100644 index 00000000000..f07792dfcc8 --- /dev/null +++ b/classes/class_animationnodeextension.rst @@ -0,0 +1,95 @@ +: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/AnimationNodeExtension.xml. + +.. _class_AnimationNodeExtension: + +AnimationNodeExtension +====================== + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** :ref:`AnimationNode` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Base class for extending :ref:`AnimationRootNode`\ s from GDScript, C#, or C++. + +.. rst-class:: classref-introduction-group + +Description +----------- + +**AnimationNodeExtension** exposes the APIs of :ref:`AnimationRootNode` to allow users to extend it from GDScript, C#, or C++. This class is not meant to be used directly, but to be extended by other classes. It is used to create custom nodes for the :ref:`AnimationTree` system. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedFloat32Array` | :ref:`_process_animation_node`\ (\ playback_info\: :ref:`PackedFloat64Array`, test_only\: :ref:`bool`\ ) |virtual| |required| | + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_remaining_time`\ (\ node_info\: :ref:`PackedFloat32Array`, break_loop\: :ref:`bool`\ ) |static| | + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_looping`\ (\ node_info\: :ref:`PackedFloat32Array`\ ) |static| | + +-----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AnimationNodeExtension_private_method__process_animation_node: + +.. rst-class:: classref-method + +:ref:`PackedFloat32Array` **_process_animation_node**\ (\ playback_info\: :ref:`PackedFloat64Array`, test_only\: :ref:`bool`\ ) |virtual| |required| :ref:`🔗` + +A version of the :ref:`AnimationNode._process()` method that is meant to be overridden by custom nodes. It returns a :ref:`PackedFloat32Array` with the processed animation data. + +The :ref:`PackedFloat64Array` parameter contains the playback information, containing the following values encoded as floating point numbers (in order): playback time and delta, start and end times, whether a seek was requested (encoded as a float greater than ``0``), whether the seek request was externally requested (encoded as a float greater than ``0``), the current :ref:`LoopedFlag` (encoded as a float), and the current blend weight. + +The function must return a :ref:`PackedFloat32Array` of the node's time info, containing the following values (in order): animation length, time position, delta, :ref:`LoopMode` (encoded as a float), whether the animation is about to end (encoded as a float greater than ``0``) and whether the animation is infinite (encoded as a float greater than ``0``). All values must be included in the returned array. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeExtension_method_get_remaining_time: + +.. rst-class:: classref-method + +:ref:`float` **get_remaining_time**\ (\ node_info\: :ref:`PackedFloat32Array`, break_loop\: :ref:`bool`\ ) |static| :ref:`🔗` + +Returns the animation's remaining time for the given node info. For looping animations, it will only return the remaining time if ``break_loop`` is ``true``, a large integer value will be returned otherwise. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeExtension_method_is_looping: + +.. rst-class:: classref-method + +:ref:`bool` **is_looping**\ (\ node_info\: :ref:`PackedFloat32Array`\ ) |static| :ref:`🔗` + +Returns ``true`` if the animation for the given ``node_info`` is looping. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index 92f8ab6f450..97b8e1ce9b4 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -32,22 +32,22 @@ After setting the request and changing the animation playback, the one-shot node animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE) # Alternative syntax (same result as above). animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE - + # Abort child animation connected to "shot" port. animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT) # Alternative syntax (same result as above). animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT - + # Abort child animation with fading out connected to "shot" port. animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT) # Alternative syntax (same result as above). animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT - + # Get current state (read-only). animation_tree.get("parameters/OneShot/active") # Alternative syntax (same result as above). animation_tree["parameters/OneShot/active"] - + # Get current internal state (read-only). animation_tree.get("parameters/OneShot/internal_active") # Alternative syntax (same result as above). @@ -57,16 +57,16 @@ After setting the request and changing the animation playback, the one-shot node // Play child animation connected to "shot" port. animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Fire); - + // Abort child animation connected to "shot" port. animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Abort); - + // Abort child animation with fading out connected to "shot" port. animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.FadeOut); - + // Get current state (read-only). animationTree.Get("parameters/OneShot/active"); - + // Get current internal state (read-only). animationTree.Get("parameters/OneShot/internal_active"); @@ -79,7 +79,7 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -96,6 +96,8 @@ Properties +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`autorestart_random_delay` | ``0.0`` | +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`break_loop_at_end` | ``false`` | + +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ | :ref:`Curve` | :ref:`fadein_curve` | | +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`fadein_time` | ``0.0`` | @@ -120,7 +122,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **OneShotRequest**: +enum **OneShotRequest**: :ref:`🔗` .. _class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_NONE: @@ -162,7 +164,7 @@ The request to fade out the animation connected to "shot" port. .. rst-class:: classref-enumeration -enum **MixMode**: +enum **MixMode**: :ref:`🔗` .. _class_AnimationNodeOneShot_constant_MIX_MODE_BLEND: @@ -193,7 +195,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **autorestart** = ``false`` +:ref:`bool` **autorestart** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -212,7 +214,7 @@ In other words, to start auto restarting, the animation must be played once with .. rst-class:: classref-property -:ref:`float` **autorestart_delay** = ``1.0`` +:ref:`float` **autorestart_delay** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -229,7 +231,7 @@ The delay after which the automatic restart is triggered, in seconds. .. rst-class:: classref-property -:ref:`float` **autorestart_random_delay** = ``0.0`` +:ref:`float` **autorestart_random_delay** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -242,18 +244,35 @@ If :ref:`autorestart` is ``true ---- +.. _class_AnimationNodeOneShot_property_break_loop_at_end: + +.. rst-class:: classref-property + +:ref:`bool` **break_loop_at_end** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_break_loop_at_end**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_loop_broken_at_end**\ (\ ) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeOneShot_property_fadein_curve: .. rst-class:: classref-property -:ref:`Curve` **fadein_curve** +:ref:`Curve` **fadein_curve** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_fadein_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_fadein_curve**\ (\ ) -Determines how cross-fading between animations is eased. If empty, the transition will be linear. +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator @@ -263,7 +282,7 @@ Determines how cross-fading between animations is eased. If empty, the transitio .. rst-class:: classref-property -:ref:`float` **fadein_time** = ``0.0`` +:ref:`float` **fadein_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -272,6 +291,8 @@ Determines how cross-fading between animations is eased. If empty, the transitio The fade-in duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 0 second and ends at 1 second during the animation. +\ **Note:** **AnimationNodeOneShot** transitions the current state after the fading has finished. + .. rst-class:: classref-item-separator ---- @@ -280,14 +301,14 @@ The fade-in duration. For example, setting this to ``1.0`` for a 5 second length .. rst-class:: classref-property -:ref:`Curve` **fadeout_curve** +:ref:`Curve` **fadeout_curve** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_fadeout_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_fadeout_curve**\ (\ ) -Determines how cross-fading between animations is eased. If empty, the transition will be linear. +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator @@ -297,7 +318,7 @@ Determines how cross-fading between animations is eased. If empty, the transitio .. rst-class:: classref-property -:ref:`float` **fadeout_time** = ``0.0`` +:ref:`float` **fadeout_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -306,6 +327,8 @@ Determines how cross-fading between animations is eased. If empty, the transitio The fade-out duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 4 second and ends at 5 second during the animation. +\ **Note:** **AnimationNodeOneShot** transitions the current state after the fading has finished. + .. rst-class:: classref-item-separator ---- @@ -314,7 +337,7 @@ The fade-out duration. For example, setting this to ``1.0`` for a 5 second lengt .. rst-class:: classref-property -:ref:`MixMode` **mix_mode** = ``0`` +:ref:`MixMode` **mix_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -324,6 +347,7 @@ The fade-out duration. For example, setting this to ``1.0`` for a 5 second lengt The blend type. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodeoutput.rst b/classes/class_animationnodeoutput.rst index 2965cafaf80..36c14f1c809 100644 --- a/classes/class_animationnodeoutput.rst +++ b/classes/class_animationnodeoutput.rst @@ -28,11 +28,12 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodestatemachine.rst b/classes/class_animationnodestatemachine.rst index aa73899bbee..3724360ee36 100644 --- a/classes/class_animationnodestatemachine.rst +++ b/classes/class_animationnodestatemachine.rst @@ -21,8 +21,6 @@ Description 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:**\ - .. tabs:: @@ -78,6 +76,8 @@ Methods +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`AnimationNode` | :ref:`get_node`\ (\ name\: :ref:`StringName`\ ) |const| | +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_node_list`\ (\ ) |const| | + +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`get_node_name`\ (\ node\: :ref:`AnimationNode`\ ) |const| | +---------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_node_position`\ (\ name\: :ref:`StringName`\ ) |const| | @@ -122,7 +122,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **StateMachineType**: +enum **StateMachineType**: :ref:`🔗` .. _class_AnimationNodeStateMachine_constant_STATE_MACHINE_TYPE_ROOT: @@ -161,14 +161,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **allow_transition_to_self** = ``false`` +:ref:`bool` **allow_transition_to_self** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_allow_transition_to_self**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_allow_transition_to_self**\ (\ ) -If ``true``, allows teleport to the self state with :ref:`AnimationNodeStateMachinePlayback.travel`. When the reset option is enabled in :ref:`AnimationNodeStateMachinePlayback.travel`, the animation is restarted. If ``false``, nothing happens on the teleportation to the self state. +If ``true``, allows teleport to the self state with :ref:`AnimationNodeStateMachinePlayback.travel()`. When the reset option is enabled in :ref:`AnimationNodeStateMachinePlayback.travel()`, the animation is restarted. If ``false``, nothing happens on the teleportation to the self state. .. rst-class:: classref-item-separator @@ -178,7 +178,7 @@ If ``true``, allows teleport to the self state with :ref:`AnimationNodeStateMach .. rst-class:: classref-property -:ref:`bool` **reset_ends** = ``false`` +:ref:`bool` **reset_ends** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -197,7 +197,7 @@ In most cases, when additional cross-fades are performed in the parent :ref:`Ani .. rst-class:: classref-property -:ref:`StateMachineType` **state_machine_type** = ``0`` +:ref:`StateMachineType` **state_machine_type** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -219,7 +219,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) +|void| **add_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`, position\: :ref:`Vector2` = Vector2(0, 0)\ ) :ref:`🔗` Adds a new animation node to the graph. The ``position`` is used for display in the editor. @@ -231,7 +231,7 @@ Adds a new animation node to the graph. The ``position`` is used for display in .. rst-class:: classref-method -|void| **add_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`, transition\: :ref:`AnimationNodeStateMachineTransition`\ ) +|void| **add_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`, transition\: :ref:`AnimationNodeStateMachineTransition`\ ) :ref:`🔗` Adds a transition between the given animation nodes. @@ -243,7 +243,7 @@ Adds a transition between the given animation nodes. .. rst-class:: classref-method -:ref:`Vector2` **get_graph_offset**\ (\ ) |const| +:ref:`Vector2` **get_graph_offset**\ (\ ) |const| :ref:`🔗` Returns the draw offset of the graph. Used for display in the editor. @@ -255,7 +255,7 @@ Returns the draw offset of the graph. Used for display in the editor. .. rst-class:: classref-method -:ref:`AnimationNode` **get_node**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`AnimationNode` **get_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the animation node with the given name. @@ -263,11 +263,23 @@ Returns the animation node with the given name. ---- +.. _class_AnimationNodeStateMachine_method_get_node_list: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`StringName`\] **get_node_list**\ (\ ) |const| :ref:`🔗` + +Returns a list containing the names of all animation nodes in this state machine. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeStateMachine_method_get_node_name: .. rst-class:: classref-method -:ref:`StringName` **get_node_name**\ (\ node\: :ref:`AnimationNode`\ ) |const| +:ref:`StringName` **get_node_name**\ (\ node\: :ref:`AnimationNode`\ ) |const| :ref:`🔗` Returns the given animation node's name. @@ -279,7 +291,7 @@ Returns the given animation node's name. .. rst-class:: classref-method -:ref:`Vector2` **get_node_position**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`Vector2` **get_node_position**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the given animation node's coordinates. Used for display in the editor. @@ -291,7 +303,7 @@ Returns the given animation node's coordinates. Used for display in the editor. .. rst-class:: classref-method -:ref:`AnimationNodeStateMachineTransition` **get_transition**\ (\ idx\: :ref:`int`\ ) |const| +:ref:`AnimationNodeStateMachineTransition` **get_transition**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given transition. @@ -303,7 +315,7 @@ Returns the given transition. .. rst-class:: classref-method -:ref:`int` **get_transition_count**\ (\ ) |const| +:ref:`int` **get_transition_count**\ (\ ) |const| :ref:`🔗` Returns the number of connections in the graph. @@ -315,7 +327,7 @@ Returns the number of connections in the graph. .. rst-class:: classref-method -:ref:`StringName` **get_transition_from**\ (\ idx\: :ref:`int`\ ) |const| +:ref:`StringName` **get_transition_from**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given transition's start node. @@ -327,7 +339,7 @@ Returns the given transition's start node. .. rst-class:: classref-method -:ref:`StringName` **get_transition_to**\ (\ idx\: :ref:`int`\ ) |const| +:ref:`StringName` **get_transition_to**\ (\ idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the given transition's end node. @@ -339,7 +351,7 @@ Returns the given transition's end node. .. rst-class:: classref-method -:ref:`bool` **has_node**\ (\ name\: :ref:`StringName`\ ) |const| +:ref:`bool` **has_node**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns ``true`` if the graph contains the given animation node. @@ -351,7 +363,7 @@ Returns ``true`` if the graph contains the given animation node. .. rst-class:: classref-method -:ref:`bool` **has_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) |const| +:ref:`bool` **has_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns ``true`` if there is a transition between the given animation nodes. @@ -363,7 +375,7 @@ Returns ``true`` if there is a transition between the given animation nodes. .. rst-class:: classref-method -|void| **remove_node**\ (\ name\: :ref:`StringName`\ ) +|void| **remove_node**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` Deletes the given animation node from the graph. @@ -375,7 +387,7 @@ Deletes the given animation node from the graph. .. rst-class:: classref-method -|void| **remove_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) +|void| **remove_transition**\ (\ from\: :ref:`StringName`, to\: :ref:`StringName`\ ) :ref:`🔗` Deletes the transition between the two specified animation nodes. @@ -387,7 +399,7 @@ Deletes the transition between the two specified animation nodes. .. rst-class:: classref-method -|void| **remove_transition_by_index**\ (\ idx\: :ref:`int`\ ) +|void| **remove_transition_by_index**\ (\ idx\: :ref:`int`\ ) :ref:`🔗` Deletes the given transition by index. @@ -399,7 +411,7 @@ Deletes the given transition by index. .. rst-class:: classref-method -|void| **rename_node**\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) +|void| **rename_node**\ (\ name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` Renames the given animation node. @@ -411,7 +423,7 @@ Renames the given animation node. .. rst-class:: classref-method -|void| **replace_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`\ ) +|void| **replace_node**\ (\ name\: :ref:`StringName`, node\: :ref:`AnimationNode`\ ) :ref:`🔗` Replaces the given animation node with a new animation node. @@ -423,7 +435,7 @@ Replaces the given animation node with a new animation node. .. rst-class:: classref-method -|void| **set_graph_offset**\ (\ offset\: :ref:`Vector2`\ ) +|void| **set_graph_offset**\ (\ offset\: :ref:`Vector2`\ ) :ref:`🔗` Sets the draw offset of the graph. Used for display in the editor. @@ -435,11 +447,12 @@ Sets the draw offset of the graph. Used for display in the editor. .. rst-class:: classref-method -|void| **set_node_position**\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) +|void| **set_node_position**\ (\ name\: :ref:`StringName`, position\: :ref:`Vector2`\ ) :ref:`🔗` 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.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index 52fb2f528ad..0755e061484 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -21,8 +21,6 @@ Description Allows control of :ref:`AnimationTree` state machines created with :ref:`AnimationNodeStateMachine`. Retrieve with ``$AnimationTree.get("parameters/playback")``. -\ **Example:**\ - .. tabs:: @@ -93,6 +91,37 @@ Methods .. rst-class:: classref-descriptions-group +Signals +------- + +.. _class_AnimationNodeStateMachinePlayback_signal_state_finished: + +.. rst-class:: classref-signal + +**state_finished**\ (\ state\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the ``state`` finishes playback. If ``state`` is a state machine set to grouped mode, its signals are passed through with its name prefixed. + +If there is a crossfade, this will be fired when the influence of the :ref:`get_fading_from_node()` animation is no longer present. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachinePlayback_signal_state_started: + +.. rst-class:: classref-signal + +**state_started**\ (\ state\: :ref:`StringName`\ ) :ref:`🔗` + +Emitted when the ``state`` starts playback. If ``state`` is a state machine set to grouped mode, its signals are passed through with its name prefixed. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- @@ -100,7 +129,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_current_length**\ (\ ) |const| +:ref:`float` **get_current_length**\ (\ ) |const| :ref:`🔗` Returns the current state length. @@ -114,7 +143,7 @@ Returns the current state length. .. rst-class:: classref-method -:ref:`StringName` **get_current_node**\ (\ ) |const| +:ref:`StringName` **get_current_node**\ (\ ) |const| :ref:`🔗` Returns the currently playing animation state. @@ -128,7 +157,7 @@ Returns the currently playing animation state. .. rst-class:: classref-method -:ref:`float` **get_current_play_position**\ (\ ) |const| +:ref:`float` **get_current_play_position**\ (\ ) |const| :ref:`🔗` Returns the playback position within the current animation state. @@ -140,7 +169,7 @@ Returns the playback position within the current animation state. .. rst-class:: classref-method -:ref:`StringName` **get_fading_from_node**\ (\ ) |const| +:ref:`StringName` **get_fading_from_node**\ (\ ) |const| :ref:`🔗` Returns the starting state of currently fading animation. @@ -152,7 +181,7 @@ Returns the starting state of currently fading animation. .. rst-class:: classref-method -:ref:`Array`\[:ref:`StringName`\] **get_travel_path**\ (\ ) |const| +:ref:`Array`\[:ref:`StringName`\] **get_travel_path**\ (\ ) |const| :ref:`🔗` Returns the current travel path as computed internally by the A\* algorithm. @@ -164,7 +193,7 @@ Returns the current travel path as computed internally by the A\* algorithm. .. rst-class:: classref-method -:ref:`bool` **is_playing**\ (\ ) |const| +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` Returns ``true`` if an animation is playing. @@ -176,7 +205,7 @@ Returns ``true`` if an animation is playing. .. rst-class:: classref-method -|void| **next**\ (\ ) +|void| **next**\ (\ ) :ref:`🔗` If there is a next path by travel or auto advance, immediately transitions from the current state to the next state. @@ -188,7 +217,7 @@ If there is a next path by travel or auto advance, immediately transitions from .. rst-class:: classref-method -|void| **start**\ (\ node\: :ref:`StringName`, reset\: :ref:`bool` = true\ ) +|void| **start**\ (\ node\: :ref:`StringName`, reset\: :ref:`bool` = true\ ) :ref:`🔗` Starts playing the given animation. @@ -202,7 +231,7 @@ If ``reset`` is ``true``, the animation is played from the beginning. .. rst-class:: classref-method -|void| **stop**\ (\ ) +|void| **stop**\ (\ ) :ref:`🔗` Stops the currently playing animation. @@ -214,7 +243,7 @@ Stops the currently playing animation. .. rst-class:: classref-method -|void| **travel**\ (\ to_node\: :ref:`StringName`, reset_on_teleport\: :ref:`bool` = true\ ) +|void| **travel**\ (\ to_node\: :ref:`StringName`, reset_on_teleport\: :ref:`bool` = true\ ) :ref:`🔗` Transitions from the current state to another one, following the shortest path. @@ -223,6 +252,7 @@ If the path does not connect from the current state, the animation will play aft If ``reset_on_teleport`` is ``true``, the animation is played from the beginning when the travel cause a teleportation. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index 5adcfccae85..b80c84889be 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -19,7 +19,7 @@ A transition within an :ref:`AnimationNodeStateMachine` is limited to the nodes connected by **AnimationNodeStateMachineTransition**. +The path generated when using :ref:`AnimationNodeStateMachinePlayback.travel()` is limited to the nodes connected by **AnimationNodeStateMachineTransition**. You can set the timing and conditions of the transition in detail. @@ -38,23 +38,25 @@ Properties .. table:: :widths: auto - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`StringName` | :ref:`advance_condition` | ``&""`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`String` | :ref:`advance_expression` | ``""`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`AdvanceMode` | :ref:`advance_mode` | ``1`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`int` | :ref:`priority` | ``1`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`bool` | :ref:`reset` | ``true`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`SwitchMode` | :ref:`switch_mode` | ``0`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`Curve` | :ref:`xfade_curve` | | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ - | :ref:`float` | :ref:`xfade_time` | ``0.0`` | - +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+----------+ + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`StringName` | :ref:`advance_condition` | ``&""`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`advance_expression` | ``""`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`AdvanceMode` | :ref:`advance_mode` | ``1`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`break_loop_at_end` | ``false`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`priority` | ``1`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`reset` | ``true`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`SwitchMode` | :ref:`switch_mode` | ``0`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`Curve` | :ref:`xfade_curve` | | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`xfade_time` | ``0.0`` | + +--------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-section-separator @@ -69,7 +71,7 @@ Signals .. rst-class:: classref-signal -**advance_condition_changed**\ (\ ) +**advance_condition_changed**\ (\ ) :ref:`🔗` Emitted when :ref:`advance_condition` is changed. @@ -86,7 +88,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **SwitchMode**: +enum **SwitchMode**: :ref:`🔗` .. _class_AnimationNodeStateMachineTransition_constant_SWITCH_MODE_IMMEDIATE: @@ -120,7 +122,7 @@ Wait for the current state playback to end, then switch to the beginning of the .. rst-class:: classref-enumeration -enum **AdvanceMode**: +enum **AdvanceMode**: :ref:`🔗` .. _class_AnimationNodeStateMachineTransition_constant_ADVANCE_MODE_DISABLED: @@ -136,7 +138,7 @@ Don't use this transition. :ref:`AdvanceMode` **ADVANCE_MODE_ENABLED** = ``1`` -Only use this transition during :ref:`AnimationNodeStateMachinePlayback.travel`. +Only use this transition during :ref:`AnimationNodeStateMachinePlayback.travel()`. .. _class_AnimationNodeStateMachineTransition_constant_ADVANCE_MODE_AUTO: @@ -144,7 +146,7 @@ Only use this transition during :ref:`AnimationNodeStateMachinePlayback.travel` **ADVANCE_MODE_AUTO** = ``2`` -Automatically use this transition if the :ref:`advance_condition` and :ref:`advance_expression` checks are true (if assigned). +Automatically use this transition if the :ref:`advance_condition` and :ref:`advance_expression` checks are ``true`` (if assigned). .. rst-class:: classref-section-separator @@ -159,7 +161,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`StringName` **advance_condition** = ``&""`` +:ref:`StringName` **advance_condition** = ``&""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -189,7 +191,7 @@ Turn on auto advance when this condition is set. The provided name will become a .. rst-class:: classref-property -:ref:`String` **advance_expression** = ``""`` +:ref:`String` **advance_expression** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -206,14 +208,31 @@ Use an expression as a condition for state machine transitions. It is possible t .. rst-class:: classref-property -:ref:`AdvanceMode` **advance_mode** = ``1`` +:ref:`AdvanceMode` **advance_mode** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_advance_mode**\ (\ value\: :ref:`AdvanceMode`\ ) - :ref:`AdvanceMode` **get_advance_mode**\ (\ ) -Determines whether the transition should disabled, enabled when using :ref:`AnimationNodeStateMachinePlayback.travel`, or traversed automatically if the :ref:`advance_condition` and :ref:`advance_expression` checks are true (if assigned). +Determines whether the transition should be disabled, enabled when using :ref:`AnimationNodeStateMachinePlayback.travel()`, or traversed automatically if the :ref:`advance_condition` and :ref:`advance_expression` checks are ``true`` (if assigned). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationNodeStateMachineTransition_property_break_loop_at_end: + +.. rst-class:: classref-property + +:ref:`bool` **break_loop_at_end** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_break_loop_at_end**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_loop_broken_at_end**\ (\ ) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. .. rst-class:: classref-item-separator @@ -223,14 +242,14 @@ Determines whether the transition should disabled, enabled when using :ref:`Anim .. rst-class:: classref-property -:ref:`int` **priority** = ``1`` +:ref:`int` **priority** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_priority**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_priority**\ (\ ) -Lower priority transitions are preferred when travelling through the tree via :ref:`AnimationNodeStateMachinePlayback.travel` or :ref:`advance_mode` is set to :ref:`ADVANCE_MODE_AUTO`. +Lower priority transitions are preferred when travelling through the tree via :ref:`AnimationNodeStateMachinePlayback.travel()` or :ref:`advance_mode` is set to :ref:`ADVANCE_MODE_AUTO`. .. rst-class:: classref-item-separator @@ -240,7 +259,7 @@ Lower priority transitions are preferred when travelling through the tree via :r .. rst-class:: classref-property -:ref:`bool` **reset** = ``true`` +:ref:`bool` **reset** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -257,7 +276,7 @@ If ``true``, the destination animation is played back from the beginning when sw .. rst-class:: classref-property -:ref:`SwitchMode` **switch_mode** = ``0`` +:ref:`SwitchMode` **switch_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -274,14 +293,14 @@ The transition type. .. rst-class:: classref-property -:ref:`Curve` **xfade_curve** +:ref:`Curve` **xfade_curve** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_xfade_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_xfade_curve**\ (\ ) -Ease curve for better control over cross-fade between this state and the next. +Ease curve for better control over cross-fade between this state and the next. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator @@ -291,7 +310,7 @@ Ease curve for better control over cross-fade between this state and the next. .. rst-class:: classref-property -:ref:`float` **xfade_time** = ``0.0`` +:ref:`float` **xfade_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -300,7 +319,10 @@ Ease curve for better control over cross-fade between this state and the next. The time to cross-fade between this state and the next. +\ **Note:** :ref:`AnimationNodeStateMachine` transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When :ref:`AnimationNodeOutput` is considered as the most upstream, so the :ref:`xfade_time` is not scaled depending on the downstream delta. See also :ref:`AnimationNodeOneShot.fadeout_time`. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodesub2.rst b/classes/class_animationnodesub2.rst index 8a62e6d4417..e627557c414 100644 --- a/classes/class_animationnodesub2.rst +++ b/classes/class_animationnodesub2.rst @@ -35,6 +35,7 @@ Tutorials - :doc:`AnimationTree <../tutorials/animation/animation_tree>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodesync.rst b/classes/class_animationnodesync.rst index ad45b322813..5de060b0fc3 100644 --- a/classes/class_animationnodesync.rst +++ b/classes/class_animationnodesync.rst @@ -14,7 +14,7 @@ AnimationNodeSync **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. +Base class for :ref:`AnimationNode`\ s with multiple input ports that must be synchronized. .. rst-class:: classref-introduction-group @@ -55,7 +55,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **sync** = ``false`` +:ref:`bool` **sync** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -67,6 +67,7 @@ If ``false``, the blended animations' frame are stopped when the blend value is If ``true``, forcing the blended animations to advance frame. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodetimescale.rst b/classes/class_animationnodetimescale.rst index 2f31c725c58..6c865f463af 100644 --- a/classes/class_animationnodetimescale.rst +++ b/classes/class_animationnodetimescale.rst @@ -28,9 +28,10 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodetimeseek.rst b/classes/class_animationnodetimeseek.rst index c9ec75ffdcd..0d7c2fe2d3a 100644 --- a/classes/class_animationnodetimeseek.rst +++ b/classes/class_animationnodetimeseek.rst @@ -32,7 +32,7 @@ After setting the time and changing the animation playback, the time seek node a animation_tree.set("parameters/TimeSeek/seek_request", 0.0) # Alternative syntax (same result as above). animation_tree["parameters/TimeSeek/seek_request"] = 0.0 - + # Play child animation from 12 second timestamp. animation_tree.set("parameters/TimeSeek/seek_request", 12.0) # Alternative syntax (same result as above). @@ -42,7 +42,7 @@ After setting the time and changing the animation playback, the time seek node a // Play child animation from the start. animationTree.Set("parameters/TimeSeek/seek_request", 0.0); - + // Play child animation from 12 second timestamp. animationTree.Set("parameters/TimeSeek/seek_request", 12.0); @@ -55,7 +55,42 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+------------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`explicit_elapse` | ``true`` | + +-------------------------+------------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimationNodeTimeSeek_property_explicit_elapse: + +.. rst-class:: classref-property + +:ref:`bool` **explicit_elapse** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_explicit_elapse**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_explicit_elapse**\ (\ ) + +If ``true``, some processes are executed to handle keys between seeks, such as calculating root motion and finding the nearest discrete key. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationnodetransition.rst b/classes/class_animationnodetransition.rst index b837d98823e..719de4008be 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -34,12 +34,12 @@ After setting the request and changing the animation playback, the transition no animation_tree.set("parameters/Transition/transition_request", "state_2") # Alternative syntax (same result as above). animation_tree["parameters/Transition/transition_request"] = "state_2" - + # Get current state name (read-only). animation_tree.get("parameters/Transition/current_state") # Alternative syntax (same result as above). animation_tree["parameters/Transition/current_state"] - + # Get current state index (read-only). animation_tree.get("parameters/Transition/current_index") # Alternative syntax (same result as above). @@ -49,10 +49,10 @@ After setting the request and changing the animation playback, the transition no // Play child animation connected to "state_2" port. animationTree.Set("parameters/Transition/transition_request", "state_2"); - + // Get current state name (read-only). animationTree.Get("parameters/Transition/current_state"); - + // Get current state index (read-only). animationTree.Get("parameters/Transition/current_index"); @@ -65,9 +65,9 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -95,15 +95,19 @@ Methods .. table:: :widths: auto - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_input_reset`\ (\ input\: :ref:`int`\ ) |const| | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_input_set_as_auto_advance`\ (\ input\: :ref:`int`\ ) |const| | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_input_as_auto_advance`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_input_reset`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_input_loop_broken_at_end`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_input_reset`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_input_set_as_auto_advance`\ (\ input\: :ref:`int`\ ) |const| | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_input_as_auto_advance`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_input_break_loop_at_end`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_input_reset`\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) | + +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -118,7 +122,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **allow_transition_to_self** = ``false`` +:ref:`bool` **allow_transition_to_self** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -135,7 +139,7 @@ If ``true``, allows transition to the self state. When the reset option is enabl .. rst-class:: classref-property -:ref:`int` **input_count** = ``0`` +:ref:`int` **input_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -152,14 +156,14 @@ The number of enabled input ports for this animation node. .. rst-class:: classref-property -:ref:`Curve` **xfade_curve** +:ref:`Curve` **xfade_curve** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_xfade_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_xfade_curve**\ (\ ) -Determines how cross-fading between animations is eased. If empty, the transition will be linear. +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator @@ -169,7 +173,7 @@ Determines how cross-fading between animations is eased. If empty, the transitio .. rst-class:: classref-property -:ref:`float` **xfade_time** = ``0.0`` +:ref:`float` **xfade_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -178,6 +182,8 @@ Determines how cross-fading between animations is eased. If empty, the transitio Cross-fading time (in seconds) between each animation connected to the inputs. +\ **Note:** **AnimationNodeTransition** transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When :ref:`AnimationNodeOutput` is considered as the most upstream, so the :ref:`xfade_time` is not scaled depending on the downstream delta. See also :ref:`AnimationNodeOneShot.fadeout_time`. + .. rst-class:: classref-section-separator ---- @@ -187,11 +193,23 @@ Cross-fading time (in seconds) between each animation connected to the inputs. Method Descriptions ------------------- +.. _class_AnimationNodeTransition_method_is_input_loop_broken_at_end: + +.. rst-class:: classref-method + +:ref:`bool` **is_input_loop_broken_at_end**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns whether the animation breaks the loop at the end of the loop cycle for transition. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeTransition_method_is_input_reset: .. rst-class:: classref-method -:ref:`bool` **is_input_reset**\ (\ input\: :ref:`int`\ ) |const| +:ref:`bool` **is_input_reset**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether the animation restarts when the animation transitions from the other animation. @@ -203,7 +221,7 @@ Returns whether the animation restarts when the animation transitions from the o .. rst-class:: classref-method -:ref:`bool` **is_input_set_as_auto_advance**\ (\ input\: :ref:`int`\ ) |const| +:ref:`bool` **is_input_set_as_auto_advance**\ (\ input\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if auto-advance is enabled for the given ``input`` index. @@ -215,7 +233,7 @@ Returns ``true`` if auto-advance is enabled for the given ``input`` index. .. rst-class:: classref-method -|void| **set_input_as_auto_advance**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **set_input_as_auto_advance**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` Enables or disables auto-advance for the given ``input`` index. If enabled, state changes to the next input after playing the animation once. If enabled for the last input state, it loops to the first. @@ -223,15 +241,28 @@ Enables or disables auto-advance for the given ``input`` index. If enabled, stat ---- +.. _class_AnimationNodeTransition_method_set_input_break_loop_at_end: + +.. rst-class:: classref-method + +|void| **set_input_break_loop_at_end**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeTransition_method_set_input_reset: .. rst-class:: classref-method -|void| **set_input_reset**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **set_input_reset**\ (\ input\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the destination animation is restarted when the animation transitions. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index 5a1ce078373..70012e0b133 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -36,7 +36,7 @@ Tutorials - :doc:`Animation documentation index <../tutorials/animation/index>` -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -46,23 +46,31 @@ Properties .. table:: :widths: auto - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`String` | :ref:`assigned_animation` | | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`String` | :ref:`autoplay` | ``""`` | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`String` | :ref:`current_animation` | ``""`` | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`float` | :ref:`current_animation_length` | | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`float` | :ref:`current_animation_position` | | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`movie_quit_on_finish` | ``false`` | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`float` | :ref:`playback_default_blend_time` | ``0.0`` | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ - | :ref:`float` | :ref:`speed_scale` | ``1.0`` | - +-----------------------------+------------------------------------------------------------------------------------------------+-----------+ + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`assigned_animation` | | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`autoplay` | ``""`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`String` | :ref:`current_animation` | ``""`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`current_animation_length` | | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`current_animation_position` | | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`movie_quit_on_finish` | ``false`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`playback_auto_capture` | ``true`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`playback_auto_capture_duration` | ``-1.0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`EaseType` | :ref:`playback_auto_capture_ease_type` | ``0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`TransitionType` | :ref:`playback_auto_capture_transition_type` | ``0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`playback_default_blend_time` | ``0.0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`speed_scale` | ``1.0`` | + +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group @@ -72,49 +80,69 @@ Methods .. table:: :widths: auto - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`StringName` | :ref:`animation_get_next`\ (\ animation_from\: :ref:`StringName`\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`animation_set_next`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear_queue`\ (\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`AnimationMethodCallMode` | :ref:`get_method_call_mode`\ (\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_playing_speed`\ (\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`AnimationProcessCallback` | :ref:`get_process_callback`\ (\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`get_queue`\ (\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`NodePath` | :ref:`get_root`\ (\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`pause`\ (\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`play`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`play_with_capture`\ (\ name\: :ref:`StringName`, duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`queue`\ (\ name\: :ref:`StringName`\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`seek`\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_method_call_mode`\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_process_callback`\ (\ mode\: :ref:`AnimationProcessCallback`\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_root`\ (\ path\: :ref:`NodePath`\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`stop`\ (\ keep_state\: :ref:`bool` = false\ ) | - +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`animation_get_next`\ (\ animation_from\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`animation_set_next`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_queue`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationMethodCallMode` | :ref:`get_method_call_mode`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playing_speed`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AnimationProcessCallback` | :ref:`get_process_callback`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_queue`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`get_root`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_section_end_time`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_section_start_time`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_section`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`pause`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_backwards`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_with_markers`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_with_markers_backwards`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_with_capture`\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`queue`\ (\ name\: :ref:`StringName`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reset_section`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_method_call_mode`\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_process_callback`\ (\ mode\: :ref:`AnimationProcessCallback`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_root`\ (\ path\: :ref:`NodePath`\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_section`\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_section_with_markers`\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ keep_state\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -129,11 +157,11 @@ Signals .. rst-class:: classref-signal -**animation_changed**\ (\ old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) +**animation_changed**\ (\ old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` -Emitted when a queued animation plays after the previous animation finished. See also :ref:`queue`. +Emitted when a queued animation plays after the previous animation finished. See also :ref:`queue()`. -\ **Note:** The signal is not emitted when the animation is changed via :ref:`play` or by an :ref:`AnimationTree`. +\ **Note:** The signal is not emitted when the animation is changed via :ref:`play()` or by an :ref:`AnimationTree`. .. rst-class:: classref-item-separator @@ -143,7 +171,7 @@ Emitted when a queued animation plays after the previous animation finished. See .. rst-class:: classref-signal -**current_animation_changed**\ (\ name\: :ref:`String`\ ) +**current_animation_changed**\ (\ name\: :ref:`String`\ ) :ref:`🔗` Emitted when :ref:`current_animation` changes. @@ -160,7 +188,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **AnimationProcessCallback**: +enum **AnimationProcessCallback**: :ref:`🔗` .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_PHYSICS: @@ -200,7 +228,7 @@ enum **AnimationProcessCallback**: .. rst-class:: classref-enumeration -enum **AnimationMethodCallMode**: +enum **AnimationMethodCallMode**: :ref:`🔗` .. _class_AnimationPlayer_constant_ANIMATION_METHOD_CALL_DEFERRED: @@ -235,7 +263,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`String` **assigned_animation** +:ref:`String` **assigned_animation** :ref:`🔗` .. rst-class:: classref-property-setget @@ -252,7 +280,7 @@ If playing, the current animation's key, otherwise, the animation last played. W .. rst-class:: classref-property -:ref:`String` **autoplay** = ``""`` +:ref:`String` **autoplay** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -269,14 +297,14 @@ The key of the animation to play when the scene loads. .. rst-class:: classref-property -:ref:`String` **current_animation** = ``""`` +:ref:`String` **current_animation** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_current_animation**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_current_animation**\ (\ ) -The key of the currently playing animation. If no animation is playing, the property's value is an empty string. Changing this value does not restart the animation. See :ref:`play` for more information on playing animations. +The key of the currently playing animation. If no animation is playing, the property's value is an empty string. Changing this value does not restart the animation. See :ref:`play()` for more information on playing animations. \ **Note:** While this property appears in the Inspector, it's not meant to be edited, and it's not saved in the scene. This property is mainly used to get the currently playing animation, and internally for animation playback tracks. For more information, see :ref:`Animation`. @@ -288,7 +316,7 @@ The key of the currently playing animation. If no animation is playing, the prop .. rst-class:: classref-property -:ref:`float` **current_animation_length** +:ref:`float` **current_animation_length** :ref:`🔗` .. rst-class:: classref-property-setget @@ -304,7 +332,7 @@ The length (in seconds) of the currently playing animation. .. rst-class:: classref-property -:ref:`float` **current_animation_position** +:ref:`float` **current_animation_position** :ref:`🔗` .. rst-class:: classref-property-setget @@ -320,14 +348,14 @@ The position (in seconds) of the currently playing animation. .. rst-class:: classref-property -:ref:`bool` **movie_quit_on_finish** = ``false`` +:ref:`bool` **movie_quit_on_finish** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_movie_quit_on_finish_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_movie_quit_on_finish_enabled**\ (\ ) -If ``true`` and the engine is running in Movie Maker mode (see :ref:`MovieWriter`), exits the engine with :ref:`SceneTree.quit` as soon as an animation is done playing in this **AnimationPlayer**. A message is printed when the engine quits for this reason. +If ``true`` and the engine is running in Movie Maker mode (see :ref:`MovieWriter`), exits the engine with :ref:`SceneTree.quit()` as soon as an animation is done playing in this **AnimationPlayer**. A message is printed when the engine quits for this reason. \ **Note:** This obeys the same logic as the :ref:`AnimationMixer.animation_finished` signal, so it will not quit the engine if the animation is set to be looping. @@ -335,11 +363,83 @@ If ``true`` and the engine is running in Movie Maker mode (see :ref:`MovieWriter ---- +.. _class_AnimationPlayer_property_playback_auto_capture: + +.. rst-class:: classref-property + +:ref:`bool` **playback_auto_capture** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_capture**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_auto_capture**\ (\ ) + +If ``true``, performs :ref:`AnimationMixer.capture()` before playback automatically. This means just :ref:`play_with_capture()` is executed with default arguments instead of :ref:`play()`. + +\ **Note:** Capture interpolation is only performed if the animation contains a capture track. See also :ref:`Animation.UPDATE_CAPTURE`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_property_playback_auto_capture_duration: + +.. rst-class:: classref-property + +:ref:`float` **playback_auto_capture_duration** = ``-1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_capture_duration**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_auto_capture_duration**\ (\ ) + +See also :ref:`play_with_capture()` and :ref:`AnimationMixer.capture()`. + +If :ref:`playback_auto_capture_duration` is negative value, the duration is set to the interval between the current position and the first key. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_property_playback_auto_capture_ease_type: + +.. rst-class:: classref-property + +:ref:`EaseType` **playback_auto_capture_ease_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_capture_ease_type**\ (\ value\: :ref:`EaseType`\ ) +- :ref:`EaseType` **get_auto_capture_ease_type**\ (\ ) + +The ease type of the capture interpolation. See also :ref:`EaseType`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_property_playback_auto_capture_transition_type: + +.. rst-class:: classref-property + +:ref:`TransitionType` **playback_auto_capture_transition_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_auto_capture_transition_type**\ (\ value\: :ref:`TransitionType`\ ) +- :ref:`TransitionType` **get_auto_capture_transition_type**\ (\ ) + +The transition type of the capture interpolation. See also :ref:`TransitionType`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_property_playback_default_blend_time: .. rst-class:: classref-property -:ref:`float` **playback_default_blend_time** = ``0.0`` +:ref:`float` **playback_default_blend_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -356,7 +456,7 @@ The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 p .. rst-class:: classref-property -:ref:`float` **speed_scale** = ``1.0`` +:ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -380,7 +480,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`StringName` **animation_get_next**\ (\ animation_from\: :ref:`StringName`\ ) |const| +:ref:`StringName` **animation_get_next**\ (\ animation_from\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the key of the animation which is queued to play after the ``animation_from`` animation. @@ -392,7 +492,7 @@ Returns the key of the animation which is queued to play after the ``animation_f .. rst-class:: classref-method -|void| **animation_set_next**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) +|void| **animation_set_next**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) :ref:`🔗` Triggers the ``animation_to`` animation when the ``animation_from`` animation completes. @@ -404,7 +504,7 @@ Triggers the ``animation_to`` animation when the ``animation_from`` animation co .. rst-class:: classref-method -|void| **clear_queue**\ (\ ) +|void| **clear_queue**\ (\ ) :ref:`🔗` Clears all queued, unplayed animations. @@ -416,7 +516,7 @@ Clears all queued, unplayed animations. .. rst-class:: classref-method -:ref:`float` **get_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| +:ref:`float` **get_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the blend time (in seconds) between two animations, referenced by their keys. @@ -428,7 +528,7 @@ Returns the blend time (in seconds) between two animations, referenced by their .. rst-class:: classref-method -:ref:`AnimationMethodCallMode` **get_method_call_mode**\ (\ ) |const| +:ref:`AnimationMethodCallMode` **get_method_call_mode**\ (\ ) |const| :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.callback_mode_method` instead. @@ -442,9 +542,9 @@ Returns the call mode used for "Call Method" tracks. .. rst-class:: classref-method -:ref:`float` **get_playing_speed**\ (\ ) |const| +:ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` -Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play` method. +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the :ref:`speed_scale` property multiplied by ``custom_speed`` argument specified when calling the :ref:`play()` method. Returns a negative value if the current animation is playing backwards. @@ -456,7 +556,7 @@ Returns a negative value if the current animation is playing backwards. .. rst-class:: classref-method -:ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| +:ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. @@ -470,7 +570,7 @@ Returns the process notification in which to update animations. .. rst-class:: classref-method -:ref:`PackedStringArray` **get_queue**\ (\ ) +:ref:`PackedStringArray` **get_queue**\ (\ ) :ref:`🔗` Returns a list of the animation keys that are currently queued to play. @@ -482,7 +582,7 @@ Returns a list of the animation keys that are currently queued to play. .. rst-class:: classref-method -:ref:`NodePath` **get_root**\ (\ ) |const| +:ref:`NodePath` **get_root**\ (\ ) |const| :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.root_node` instead. @@ -492,11 +592,47 @@ Returns the node which node path references will travel from. ---- +.. _class_AnimationPlayer_method_get_section_end_time: + +.. rst-class:: classref-method + +:ref:`float` **get_section_end_time**\ (\ ) |const| :ref:`🔗` + +Returns the end time of the section currently being played. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_get_section_start_time: + +.. rst-class:: classref-method + +:ref:`float` **get_section_start_time**\ (\ ) |const| :ref:`🔗` + +Returns the start time of the section currently being played. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_has_section: + +.. rst-class:: classref-method + +:ref:`bool` **has_section**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if an animation is currently playing with a section. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_is_playing: .. rst-class:: classref-method -:ref:`bool` **is_playing**\ (\ ) |const| +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale` and/or ``custom_speed`` are ``0``). @@ -508,11 +644,11 @@ Returns ``true`` if an animation is currently playing (even if :ref:`speed_scale .. rst-class:: classref-method -|void| **pause**\ (\ ) +|void| **pause**\ (\ ) :ref:`🔗` -Pauses the currently playing animation. The :ref:`current_animation_position` will be kept and calling :ref:`play` or :ref:`play_backwards` without arguments or with the same animation name as :ref:`assigned_animation` will resume the animation. +Pauses the currently playing animation. The :ref:`current_animation_position` will be kept and calling :ref:`play()` or :ref:`play_backwards()` without arguments or with the same animation name as :ref:`assigned_animation` will resume the animation. -See also :ref:`stop`. +See also :ref:`stop()`. .. rst-class:: classref-item-separator @@ -522,11 +658,11 @@ See also :ref:`stop`. .. rst-class:: classref-method -|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) +|void| **play**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` Plays the animation with key ``name``. Custom blend times and speed can be set. -The ``from_end`` option only affects when switching to a new animation track, or if the same track but at the start or end. It does not affect resuming playback that was paused in the middle of an animation. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards`). +The ``from_end`` option only affects when switching to a new animation track, or if the same track but at the start or end. It does not affect resuming playback that was paused in the middle of an animation. If ``custom_speed`` is negative and ``from_end`` is ``true``, the animation will play backwards (which is equivalent to calling :ref:`play_backwards()`). The **AnimationPlayer** keeps track of its current or last played animation with :ref:`assigned_animation`. If this method is called with that same animation ``name``, or with no ``name`` parameter, the assigned animation will resume playing if it was paused. @@ -540,11 +676,67 @@ The **AnimationPlayer** keeps track of its current or last played animation with .. rst-class:: classref-method -|void| **play_backwards**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) +|void| **play_backwards**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` Plays the animation with key ``name`` in reverse. -This method is a shorthand for :ref:`play` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. +This method is a shorthand for :ref:`play()` with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section: + +.. rst-class:: classref-method + +|void| **play_section**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` + +Plays the animation with key ``name`` and the section starting from ``start_time`` and ending on ``end_time``. See also :ref:`play()`. + +Setting ``start_time`` to a value outside the range of the animation means the start of the animation will be used instead, and setting ``end_time`` to a value outside the range of the animation means the end of the animation will be used instead. ``start_time`` cannot be equal to ``end_time``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_backwards: + +.. rst-class:: classref-method + +|void| **play_section_backwards**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` + +Plays the animation with key ``name`` and the section starting from ``start_time`` and ending on ``end_time`` in reverse. + +This method is a shorthand for :ref:`play_section()` with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_with_markers: + +.. rst-class:: classref-method + +|void| **play_section_with_markers**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` + +Plays the animation with key ``name`` and the section starting from ``start_marker`` and ending on ``end_marker``. + +If the start marker is empty, the section starts from the beginning of the animation. If the end marker is empty, the section ends on the end of the animation. See also :ref:`play()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_with_markers_backwards: + +.. rst-class:: classref-method + +|void| **play_section_with_markers_backwards**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` + +Plays the animation with key ``name`` and the section starting from ``start_marker`` and ending on ``end_marker`` in reverse. + +This method is a shorthand for :ref:`play_section_with_markers()` with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. .. rst-class:: classref-item-separator @@ -554,16 +746,18 @@ This method is a shorthand for :ref:`play` wi .. rst-class:: classref-method -|void| **play_with_capture**\ (\ name\: :ref:`StringName`, duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) +|void| **play_with_capture**\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) :ref:`🔗` -See :ref:`AnimationMixer.capture`. It is almost the same as the following: +See also :ref:`AnimationMixer.capture()`. + +You can use this method to use more detailed options for capture than those performed by :ref:`playback_auto_capture`. When :ref:`playback_auto_capture` is ``false``, this method is almost the same as the following: :: capture(name, duration, trans_type, ease_type) play(name, custom_blend, custom_speed, from_end) -If name is blank, it specifies :ref:`assigned_animation`. +If ``name`` is blank, it specifies :ref:`assigned_animation`. If ``duration`` is a negative value, the duration is set to the interval between the current position and the first key, when ``from_end`` is ``true``, uses the interval between the current position and the last key instead. @@ -577,9 +771,9 @@ If ``duration`` is a negative value, the duration is set to the interval between .. rst-class:: classref-method -|void| **queue**\ (\ name\: :ref:`StringName`\ ) +|void| **queue**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` -Queues an animation for playback once the current one is done. +Queues an animation for playback once the current animation and all previously queued animations are done. \ **Note:** If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow. @@ -587,17 +781,29 @@ Queues an animation for playback once the current one is done. ---- +.. _class_AnimationPlayer_method_reset_section: + +.. rst-class:: classref-method + +|void| **reset_section**\ (\ ) :ref:`🔗` + +Resets the current section. Does nothing if a section has not been set. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_seek: .. rst-class:: classref-method -|void| **seek**\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) +|void| **seek**\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) :ref:`🔗` Seeks the animation to the ``seconds`` point in time (in seconds). If ``update`` is ``true``, the animation updates too, otherwise it updates at process time. Events between the current frame and ``seconds`` are skipped. If ``update_only`` is ``true``, the method / audio / animation playback tracks will not be processed. -\ **Note:** Seeking to the end of the animation doesn't emit :ref:`AnimationMixer.animation_finished`. If you want to skip animation and emit the signal, use :ref:`AnimationMixer.advance`. +\ **Note:** Seeking to the end of the animation doesn't emit :ref:`AnimationMixer.animation_finished`. If you want to skip animation and emit the signal, use :ref:`AnimationMixer.advance()`. .. rst-class:: classref-item-separator @@ -607,7 +813,7 @@ If ``update_only`` is ``true``, the method / audio / animation playback tracks w .. rst-class:: classref-method -|void| **set_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) +|void| **set_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) :ref:`🔗` Specifies a blend time (in seconds) between two animations, referenced by their keys. @@ -619,7 +825,7 @@ Specifies a blend time (in seconds) between two animations, referenced by their .. rst-class:: classref-method -|void| **set_method_call_mode**\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) +|void| **set_method_call_mode**\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.callback_mode_method` instead. @@ -633,7 +839,7 @@ Sets the call mode used for "Call Method" tracks. .. rst-class:: classref-method -|void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) +|void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. @@ -647,7 +853,7 @@ Sets the process notification in which to update animations. .. rst-class:: classref-method -|void| **set_root**\ (\ path\: :ref:`NodePath`\ ) +|void| **set_root**\ (\ path\: :ref:`NodePath`\ ) :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.root_node` instead. @@ -657,19 +863,46 @@ Sets the node which node path references will travel from. ---- +.. _class_AnimationPlayer_method_set_section: + +.. rst-class:: classref-method + +|void| **set_section**\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) :ref:`🔗` + +Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See also :ref:`play_section()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_section_with_markers: + +.. rst-class:: classref-method + +|void| **set_section_with_markers**\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) :ref:`🔗` + +Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See also :ref:`play_section_with_markers()`. + +If the argument is empty, the section uses the beginning or end of the animation. If both are empty, it means that the section is not set. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_stop: .. rst-class:: classref-method -|void| **stop**\ (\ keep_state\: :ref:`bool` = false\ ) +|void| **stop**\ (\ keep_state\: :ref:`bool` = false\ ) :ref:`🔗` -Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause`. +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also :ref:`pause()`. If ``keep_state`` is ``true``, the animation state is not updated visually. \ **Note:** The method / audio / animation playback tracks will not be processed by this method. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationrootnode.rst b/classes/class_animationrootnode.rst index 8281adc15c3..20aea2e587a 100644 --- a/classes/class_animationrootnode.rst +++ b/classes/class_animationrootnode.rst @@ -33,6 +33,7 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_animationtree.rst b/classes/class_animationtree.rst index 63cbe82ca50..096f6de963f 100644 --- a/classes/class_animationtree.rst +++ b/classes/class_animationtree.rst @@ -30,7 +30,7 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -79,7 +79,7 @@ Signals .. rst-class:: classref-signal -**animation_player_changed**\ (\ ) +**animation_player_changed**\ (\ ) :ref:`🔗` Emitted when the :ref:`anim_player` is changed. @@ -96,7 +96,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **AnimationProcessCallback**: +enum **AnimationProcessCallback**: :ref:`🔗` .. _class_AnimationTree_constant_ANIMATION_PROCESS_PHYSICS: @@ -141,7 +141,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`NodePath` **advance_expression_base_node** = ``NodePath(".")`` +:ref:`NodePath` **advance_expression_base_node** = ``NodePath(".")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -158,7 +158,7 @@ The path to the :ref:`Node` used to evaluate the :ref:`AnimationNode .. rst-class:: classref-property -:ref:`NodePath` **anim_player** = ``NodePath("")`` +:ref:`NodePath` **anim_player** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -175,7 +175,7 @@ The path to the :ref:`AnimationPlayer` used for animating .. rst-class:: classref-property -:ref:`AnimationRootNode` **tree_root** +:ref:`AnimationRootNode` **tree_root** :ref:`🔗` .. rst-class:: classref-property-setget @@ -197,7 +197,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| +:ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. @@ -211,13 +211,14 @@ Returns the process notification in which to update animations. .. rst-class:: classref-method -|void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) +|void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) :ref:`🔗` **Deprecated:** Use :ref:`AnimationMixer.callback_mode_process` instead. Sets the process notification in which to update animations. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index d33554bad8d..47248ca9945 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -35,11 +35,11 @@ Tutorials - :doc:`Using Area2D <../tutorials/physics/using_area_2d>` -- `2D Dodge The Creeps Demo `__ +- `2D Dodge The Creeps Demo `__ -- `2D Pong Demo `__ +- `2D Pong Demo `__ -- `2D Platformer Demo `__ +- `2D Platformer Demo `__ .. rst-class:: classref-reftable-group @@ -116,7 +116,7 @@ Signals .. rst-class:: classref-signal -**area_entered**\ (\ area\: :ref:`Area2D`\ ) +**area_entered**\ (\ area\: :ref:`Area2D`\ ) :ref:`🔗` Emitted when the received ``area`` enters this area. Requires :ref:`monitoring` to be set to ``true``. @@ -128,7 +128,7 @@ Emitted when the received ``area`` enters this area. Requires :ref:`monitoring`\ ) +**area_exited**\ (\ area\: :ref:`Area2D`\ ) :ref:`🔗` Emitted when the received ``area`` exits this area. Requires :ref:`monitoring` to be set to ``true``. @@ -140,13 +140,13 @@ Emitted when the received ``area`` exits this area. Requires :ref:`monitoring`, area\: :ref:`Area2D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**area_shape_entered**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area2D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape2D` of the received ``area`` enters a shape of this area. Requires :ref:`monitoring` to be set to ``true``. \ ``local_shape_index`` and ``area_shape_index`` contain indices of the interacting shapes from this area and the other area, respectively. ``area_rid`` contains the :ref:`RID` of the other area. These values can be used with the :ref:`PhysicsServer2D`. -\ **Example of getting the** :ref:`CollisionShape2D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape2D` node from the shape index: .. tabs:: @@ -155,7 +155,7 @@ Emitted when a :ref:`Shape2D` of the received ``area`` enters a s var other_shape_owner = area.shape_find_owner(area_shape_index) var other_shape_node = area.shape_owner_get_owner(other_shape_owner) - + var local_shape_owner = shape_find_owner(local_shape_index) var local_shape_node = shape_owner_get_owner(local_shape_owner) @@ -169,7 +169,7 @@ Emitted when a :ref:`Shape2D` of the received ``area`` enters a s .. rst-class:: classref-signal -**area_shape_exited**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area2D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**area_shape_exited**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area2D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape2D` of the received ``area`` exits a shape of this area. Requires :ref:`monitoring` to be set to ``true``. @@ -183,7 +183,7 @@ See also :ref:`area_shape_entered`. .. rst-class:: classref-signal -**body_entered**\ (\ body\: :ref:`Node2D`\ ) +**body_entered**\ (\ body\: :ref:`Node2D`\ ) :ref:`🔗` Emitted when the received ``body`` enters this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. @@ -195,7 +195,7 @@ Emitted when the received ``body`` enters this area. ``body`` can be a :ref:`Phy .. rst-class:: classref-signal -**body_exited**\ (\ body\: :ref:`Node2D`\ ) +**body_exited**\ (\ body\: :ref:`Node2D`\ ) :ref:`🔗` Emitted when the received ``body`` exits this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. @@ -207,13 +207,13 @@ Emitted when the received ``body`` exits this area. ``body`` can be a :ref:`Phys .. rst-class:: classref-signal -**body_shape_entered**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node2D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**body_shape_entered**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node2D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape2D` of the received ``body`` enters a shape of this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. \ ``local_shape_index`` and ``body_shape_index`` contain indices of the interacting shapes from this area and the interacting body, respectively. ``body_rid`` contains the :ref:`RID` of the body. These values can be used with the :ref:`PhysicsServer2D`. -\ **Example of getting the** :ref:`CollisionShape2D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape2D` node from the shape index: .. tabs:: @@ -222,7 +222,7 @@ Emitted when a :ref:`Shape2D` of the received ``body`` enters a s var body_shape_owner = body.shape_find_owner(body_shape_index) var body_shape_node = body.shape_owner_get_owner(body_shape_owner) - + var local_shape_owner = shape_find_owner(local_shape_index) var local_shape_node = shape_owner_get_owner(local_shape_owner) @@ -236,7 +236,7 @@ Emitted when a :ref:`Shape2D` of the received ``body`` enters a s .. rst-class:: classref-signal -**body_shape_exited**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node2D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**body_shape_exited**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node2D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape2D` of the received ``body`` exits a shape of this area. ``body`` can be a :ref:`PhysicsBody2D` or a :ref:`TileMap`. :ref:`TileMap`\ s are detected if their :ref:`TileSet` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. @@ -255,7 +255,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **SpaceOverride**: +enum **SpaceOverride**: :ref:`🔗` .. _class_Area2D_constant_SPACE_OVERRIDE_DISABLED: @@ -310,7 +310,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **angular_damp** = ``1.0`` +:ref:`float` **angular_damp** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -329,14 +329,14 @@ See :ref:`ProjectSettings.physics/2d/default_angular_damp` **angular_damp_space_override** = ``0`` +:ref:`SpaceOverride` **angular_damp_space_override** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_angular_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) - :ref:`SpaceOverride` **get_angular_damp_space_override_mode**\ (\ ) -Override mode for angular damping calculations within this area. See :ref:`SpaceOverride` for possible values. +Override mode for angular damping calculations within this area. .. rst-class:: classref-item-separator @@ -346,7 +346,7 @@ Override mode for angular damping calculations within this area. See :ref:`Space .. rst-class:: classref-property -:ref:`StringName` **audio_bus_name** = ``&"Master"`` +:ref:`StringName` **audio_bus_name** = ``&"Master"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -363,7 +363,7 @@ The name of the area's audio bus. .. rst-class:: classref-property -:ref:`bool` **audio_bus_override** = ``false`` +:ref:`bool` **audio_bus_override** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -380,7 +380,7 @@ If ``true``, the area's audio bus overrides the default audio bus. .. rst-class:: classref-property -:ref:`float` **gravity** = ``980.0`` +:ref:`float` **gravity** = ``980.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -397,7 +397,7 @@ The area's gravity intensity (in pixels per second squared). This value multipli .. rst-class:: classref-property -:ref:`Vector2` **gravity_direction** = ``Vector2(0, 1)`` +:ref:`Vector2` **gravity_direction** = ``Vector2(0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -414,7 +414,7 @@ The area's gravity vector (not normalized). .. rst-class:: classref-property -:ref:`bool` **gravity_point** = ``false`` +:ref:`bool` **gravity_point** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -431,7 +431,7 @@ If ``true``, gravity is calculated from a point (set via :ref:`gravity_point_cen .. rst-class:: classref-property -:ref:`Vector2` **gravity_point_center** = ``Vector2(0, 1)`` +:ref:`Vector2` **gravity_point_center** = ``Vector2(0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -448,7 +448,7 @@ If gravity is a point (see :ref:`gravity_point` **gravity_point_unit_distance** = ``0.0`` +:ref:`float` **gravity_point_unit_distance** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -467,14 +467,14 @@ The above is true only when the unit distance is a positive number. When this is .. rst-class:: classref-property -:ref:`SpaceOverride` **gravity_space_override** = ``0`` +:ref:`SpaceOverride` **gravity_space_override** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_gravity_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) - :ref:`SpaceOverride` **get_gravity_space_override_mode**\ (\ ) -Override mode for gravity calculations within this area. See :ref:`SpaceOverride` for possible values. +Override mode for gravity calculations within this area. .. rst-class:: classref-item-separator @@ -484,7 +484,7 @@ Override mode for gravity calculations within this area. See :ref:`SpaceOverride .. rst-class:: classref-property -:ref:`float` **linear_damp** = ``0.1`` +:ref:`float` **linear_damp** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -503,14 +503,14 @@ See :ref:`ProjectSettings.physics/2d/default_linear_damp` **linear_damp_space_override** = ``0`` +:ref:`SpaceOverride` **linear_damp_space_override** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_linear_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) - :ref:`SpaceOverride` **get_linear_damp_space_override_mode**\ (\ ) -Override mode for linear damping calculations within this area. See :ref:`SpaceOverride` for possible values. +Override mode for linear damping calculations within this area. .. rst-class:: classref-item-separator @@ -520,7 +520,7 @@ Override mode for linear damping calculations within this area. See :ref:`SpaceO .. rst-class:: classref-property -:ref:`bool` **monitorable** = ``true`` +:ref:`bool` **monitorable** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -537,7 +537,7 @@ If ``true``, other monitoring areas can detect this area. .. rst-class:: classref-property -:ref:`bool` **monitoring** = ``true`` +:ref:`bool` **monitoring** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -554,7 +554,7 @@ If ``true``, the area detects bodies or areas entering and exiting it. .. rst-class:: classref-property -:ref:`int` **priority** = ``0`` +:ref:`int` **priority** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -576,7 +576,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Array`\[:ref:`Area2D`\] **get_overlapping_areas**\ (\ ) |const| +:ref:`Array`\[:ref:`Area2D`\] **get_overlapping_areas**\ (\ ) |const| :ref:`🔗` Returns a list of intersecting **Area2D**\ s. The overlapping area's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. @@ -590,7 +590,7 @@ For performance reasons (collisions are all processed at the same time) this lis .. rst-class:: classref-method -:ref:`Array`\[:ref:`Node2D`\] **get_overlapping_bodies**\ (\ ) |const| +:ref:`Array`\[:ref:`Node2D`\] **get_overlapping_bodies**\ (\ ) |const| :ref:`🔗` Returns a list of intersecting :ref:`PhysicsBody2D`\ s and :ref:`TileMap`\ s. The overlapping body's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. @@ -604,7 +604,7 @@ For performance reasons (collisions are all processed at the same time) this lis .. rst-class:: classref-method -:ref:`bool` **has_overlapping_areas**\ (\ ) |const| +:ref:`bool` **has_overlapping_areas**\ (\ ) |const| :ref:`🔗` Returns ``true`` if intersecting any **Area2D**\ s, otherwise returns ``false``. The overlapping area's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. @@ -618,7 +618,7 @@ For performance reasons (collisions are all processed at the same time) the list .. rst-class:: classref-method -:ref:`bool` **has_overlapping_bodies**\ (\ ) |const| +:ref:`bool` **has_overlapping_bodies**\ (\ ) |const| :ref:`🔗` Returns ``true`` if intersecting any :ref:`PhysicsBody2D`\ s or :ref:`TileMap`\ s, otherwise returns ``false``. The overlapping body's :ref:`CollisionObject2D.collision_layer` must be part of this area's :ref:`CollisionObject2D.collision_mask` in order to be detected. @@ -632,7 +632,7 @@ For performance reasons (collisions are all processed at the same time) the list .. rst-class:: classref-method -:ref:`bool` **overlaps_area**\ (\ area\: :ref:`Node`\ ) |const| +:ref:`bool` **overlaps_area**\ (\ area\: :ref:`Node`\ ) |const| :ref:`🔗` Returns ``true`` if the given **Area2D** intersects or overlaps this **Area2D**, ``false`` otherwise. @@ -646,7 +646,7 @@ Returns ``true`` if the given **Area2D** intersects or overlaps this **Area2D**, .. rst-class:: classref-method -:ref:`bool` **overlaps_body**\ (\ body\: :ref:`Node`\ ) |const| +:ref:`bool` **overlaps_body**\ (\ body\: :ref:`Node`\ ) |const| :ref:`🔗` Returns ``true`` if the given physics body intersects or overlaps this **Area2D**, ``false`` otherwise. @@ -655,6 +655,7 @@ Returns ``true`` if the given physics body intersects or overlaps this **Area2D* The ``body`` argument can either be a :ref:`PhysicsBody2D` or a :ref:`TileMap` instance. While TileMaps are not physics bodies themselves, they register their tiles with collision shapes as a virtual physics body. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_area3d.rst b/classes/class_area3d.rst index fdce53bdcb9..93590202c88 100644 --- a/classes/class_area3d.rst +++ b/classes/class_area3d.rst @@ -37,9 +37,9 @@ Tutorials - :doc:`Using Area2D <../tutorials/physics/using_area_2d>` -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `GUI in 3D Demo `__ +- `GUI in 3D Viewport Demo `__ .. rst-class:: classref-reftable-group @@ -130,7 +130,7 @@ Signals .. rst-class:: classref-signal -**area_entered**\ (\ area\: :ref:`Area3D`\ ) +**area_entered**\ (\ area\: :ref:`Area3D`\ ) :ref:`🔗` Emitted when the received ``area`` enters this area. Requires :ref:`monitoring` to be set to ``true``. @@ -142,7 +142,7 @@ Emitted when the received ``area`` enters this area. Requires :ref:`monitoring`\ ) +**area_exited**\ (\ area\: :ref:`Area3D`\ ) :ref:`🔗` Emitted when the received ``area`` exits this area. Requires :ref:`monitoring` to be set to ``true``. @@ -154,13 +154,13 @@ Emitted when the received ``area`` exits this area. Requires :ref:`monitoring`, area\: :ref:`Area3D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**area_shape_entered**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area3D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape3D` of the received ``area`` enters a shape of this area. Requires :ref:`monitoring` to be set to ``true``. \ ``local_shape_index`` and ``area_shape_index`` contain indices of the interacting shapes from this area and the other area, respectively. ``area_rid`` contains the :ref:`RID` of the other area. These values can be used with the :ref:`PhysicsServer3D`. -\ **Example of getting the** :ref:`CollisionShape3D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape3D` node from the shape index: .. tabs:: @@ -169,7 +169,7 @@ Emitted when a :ref:`Shape3D` of the received ``area`` enters a s var other_shape_owner = area.shape_find_owner(area_shape_index) var other_shape_node = area.shape_owner_get_owner(other_shape_owner) - + var local_shape_owner = shape_find_owner(local_shape_index) var local_shape_node = shape_owner_get_owner(local_shape_owner) @@ -183,7 +183,7 @@ Emitted when a :ref:`Shape3D` of the received ``area`` enters a s .. rst-class:: classref-signal -**area_shape_exited**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area3D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**area_shape_exited**\ (\ area_rid\: :ref:`RID`, area\: :ref:`Area3D`, area_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape3D` of the received ``area`` exits a shape of this area. Requires :ref:`monitoring` to be set to ``true``. @@ -197,7 +197,7 @@ See also :ref:`area_shape_entered`. .. rst-class:: classref-signal -**body_entered**\ (\ body\: :ref:`Node3D`\ ) +**body_entered**\ (\ body\: :ref:`Node3D`\ ) :ref:`🔗` Emitted when the received ``body`` enters this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. @@ -209,7 +209,7 @@ Emitted when the received ``body`` enters this area. ``body`` can be a :ref:`Phy .. rst-class:: classref-signal -**body_exited**\ (\ body\: :ref:`Node3D`\ ) +**body_exited**\ (\ body\: :ref:`Node3D`\ ) :ref:`🔗` Emitted when the received ``body`` exits this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. @@ -221,13 +221,13 @@ Emitted when the received ``body`` exits this area. ``body`` can be a :ref:`Phys .. rst-class:: classref-signal -**body_shape_entered**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node3D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**body_shape_entered**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node3D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape3D` of the received ``body`` enters a shape of this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. \ ``local_shape_index`` and ``body_shape_index`` contain indices of the interacting shapes from this area and the interacting body, respectively. ``body_rid`` contains the :ref:`RID` of the body. These values can be used with the :ref:`PhysicsServer3D`. -\ **Example of getting the** :ref:`CollisionShape3D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape3D` node from the shape index: .. tabs:: @@ -236,7 +236,7 @@ Emitted when a :ref:`Shape3D` of the received ``body`` enters a s var body_shape_owner = body.shape_find_owner(body_shape_index) var body_shape_node = body.shape_owner_get_owner(body_shape_owner) - + var local_shape_owner = shape_find_owner(local_shape_index) var local_shape_node = shape_owner_get_owner(local_shape_owner) @@ -250,7 +250,7 @@ Emitted when a :ref:`Shape3D` of the received ``body`` enters a s .. rst-class:: classref-signal -**body_shape_exited**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node3D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) +**body_shape_exited**\ (\ body_rid\: :ref:`RID`, body\: :ref:`Node3D`, body_shape_index\: :ref:`int`, local_shape_index\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`Shape3D` of the received ``body`` exits a shape of this area. ``body`` can be a :ref:`PhysicsBody3D` or a :ref:`GridMap`. :ref:`GridMap`\ s are detected if their :ref:`MeshLibrary` has collision shapes configured. Requires :ref:`monitoring` to be set to ``true``. @@ -269,7 +269,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **SpaceOverride**: +enum **SpaceOverride**: :ref:`🔗` .. _class_Area3D_constant_SPACE_OVERRIDE_DISABLED: @@ -324,7 +324,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **angular_damp** = ``0.1`` +:ref:`float` **angular_damp** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -343,14 +343,14 @@ See :ref:`ProjectSettings.physics/3d/default_angular_damp` **angular_damp_space_override** = ``0`` +:ref:`SpaceOverride` **angular_damp_space_override** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_angular_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) - :ref:`SpaceOverride` **get_angular_damp_space_override_mode**\ (\ ) -Override mode for angular damping calculations within this area. See :ref:`SpaceOverride` for possible values. +Override mode for angular damping calculations within this area. .. rst-class:: classref-item-separator @@ -360,7 +360,7 @@ Override mode for angular damping calculations within this area. See :ref:`Space .. rst-class:: classref-property -:ref:`StringName` **audio_bus_name** = ``&"Master"`` +:ref:`StringName` **audio_bus_name** = ``&"Master"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -377,7 +377,7 @@ The name of the area's audio bus. .. rst-class:: classref-property -:ref:`bool` **audio_bus_override** = ``false`` +:ref:`bool` **audio_bus_override** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -394,7 +394,7 @@ If ``true``, the area's audio bus overrides the default audio bus. .. rst-class:: classref-property -:ref:`float` **gravity** = ``9.8`` +:ref:`float` **gravity** = ``9.8`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -411,7 +411,7 @@ The area's gravity intensity (in meters per second squared). This value multipli .. rst-class:: classref-property -:ref:`Vector3` **gravity_direction** = ``Vector3(0, -1, 0)`` +:ref:`Vector3` **gravity_direction** = ``Vector3(0, -1, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -428,7 +428,7 @@ The area's gravity vector (not normalized). .. rst-class:: classref-property -:ref:`bool` **gravity_point** = ``false`` +:ref:`bool` **gravity_point** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -445,7 +445,7 @@ If ``true``, gravity is calculated from a point (set via :ref:`gravity_point_cen .. rst-class:: classref-property -:ref:`Vector3` **gravity_point_center** = ``Vector3(0, -1, 0)`` +:ref:`Vector3` **gravity_point_center** = ``Vector3(0, -1, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -462,7 +462,7 @@ If gravity is a point (see :ref:`gravity_point` **gravity_point_unit_distance** = ``0.0`` +:ref:`float` **gravity_point_unit_distance** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -481,14 +481,14 @@ The above is true only when the unit distance is a positive number. When this is .. rst-class:: classref-property -:ref:`SpaceOverride` **gravity_space_override** = ``0`` +:ref:`SpaceOverride` **gravity_space_override** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_gravity_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) - :ref:`SpaceOverride` **get_gravity_space_override_mode**\ (\ ) -Override mode for gravity calculations within this area. See :ref:`SpaceOverride` for possible values. +Override mode for gravity calculations within this area. .. rst-class:: classref-item-separator @@ -498,7 +498,7 @@ Override mode for gravity calculations within this area. See :ref:`SpaceOverride .. rst-class:: classref-property -:ref:`float` **linear_damp** = ``0.1`` +:ref:`float` **linear_damp** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -517,14 +517,14 @@ See :ref:`ProjectSettings.physics/3d/default_linear_damp` **linear_damp_space_override** = ``0`` +:ref:`SpaceOverride` **linear_damp_space_override** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_linear_damp_space_override_mode**\ (\ value\: :ref:`SpaceOverride`\ ) - :ref:`SpaceOverride` **get_linear_damp_space_override_mode**\ (\ ) -Override mode for linear damping calculations within this area. See :ref:`SpaceOverride` for possible values. +Override mode for linear damping calculations within this area. .. rst-class:: classref-item-separator @@ -534,7 +534,7 @@ Override mode for linear damping calculations within this area. See :ref:`SpaceO .. rst-class:: classref-property -:ref:`bool` **monitorable** = ``true`` +:ref:`bool` **monitorable** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -551,7 +551,7 @@ If ``true``, other monitoring areas can detect this area. .. rst-class:: classref-property -:ref:`bool` **monitoring** = ``true`` +:ref:`bool` **monitoring** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -568,7 +568,7 @@ If ``true``, the area detects bodies or areas entering and exiting it. .. rst-class:: classref-property -:ref:`int` **priority** = ``0`` +:ref:`int` **priority** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -585,7 +585,7 @@ The area's priority. Higher priority areas are processed first. The :ref:`World3 .. rst-class:: classref-property -:ref:`float` **reverb_bus_amount** = ``0.0`` +:ref:`float` **reverb_bus_amount** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -602,7 +602,7 @@ The degree to which this area applies reverb to its associated audio. Ranges fro .. rst-class:: classref-property -:ref:`bool` **reverb_bus_enabled** = ``false`` +:ref:`bool` **reverb_bus_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -619,7 +619,7 @@ If ``true``, the area applies reverb to its associated audio. .. rst-class:: classref-property -:ref:`StringName` **reverb_bus_name** = ``&"Master"`` +:ref:`StringName` **reverb_bus_name** = ``&"Master"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -636,7 +636,7 @@ The name of the reverb bus to use for this area's associated audio. .. rst-class:: classref-property -:ref:`float` **reverb_bus_uniformity** = ``0.0`` +:ref:`float` **reverb_bus_uniformity** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -653,7 +653,7 @@ The degree to which this area's reverb is a uniform effect. Ranges from ``0`` to .. rst-class:: classref-property -:ref:`float` **wind_attenuation_factor** = ``0.0`` +:ref:`float` **wind_attenuation_factor** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -662,6 +662,8 @@ The degree to which this area's reverb is a uniform effect. Ranges from ``0`` to The exponential rate at which wind force decreases with distance from its origin. +\ **Note:** This wind force only applies to :ref:`SoftBody3D` nodes. Other physics bodies are currently not affected by wind. + .. rst-class:: classref-item-separator ---- @@ -670,7 +672,7 @@ The exponential rate at which wind force decreases with distance from its origin .. rst-class:: classref-property -:ref:`float` **wind_force_magnitude** = ``0.0`` +:ref:`float` **wind_force_magnitude** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -679,6 +681,8 @@ The exponential rate at which wind force decreases with distance from its origin The magnitude of area-specific wind force. +\ **Note:** This wind force only applies to :ref:`SoftBody3D` nodes. Other physics bodies are currently not affected by wind. + .. rst-class:: classref-item-separator ---- @@ -687,7 +691,7 @@ The magnitude of area-specific wind force. .. rst-class:: classref-property -:ref:`NodePath` **wind_source_path** = ``NodePath("")`` +:ref:`NodePath` **wind_source_path** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -696,6 +700,8 @@ The magnitude of area-specific wind force. The :ref:`Node3D` which is used to specify the direction and origin of an area-specific wind force. The direction is opposite to the z-axis of the :ref:`Node3D`'s local transform, and its origin is the origin of the :ref:`Node3D`'s local transform. +\ **Note:** This wind force only applies to :ref:`SoftBody3D` nodes. Other physics bodies are currently not affected by wind. + .. rst-class:: classref-section-separator ---- @@ -709,7 +715,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Array`\[:ref:`Area3D`\] **get_overlapping_areas**\ (\ ) |const| +:ref:`Array`\[:ref:`Area3D`\] **get_overlapping_areas**\ (\ ) |const| :ref:`🔗` Returns a list of intersecting **Area3D**\ s. The overlapping area's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. @@ -723,7 +729,7 @@ For performance reasons (collisions are all processed at the same time) this lis .. rst-class:: classref-method -:ref:`Array`\[:ref:`Node3D`\] **get_overlapping_bodies**\ (\ ) |const| +:ref:`Array`\[:ref:`Node3D`\] **get_overlapping_bodies**\ (\ ) |const| :ref:`🔗` Returns a list of intersecting :ref:`PhysicsBody3D`\ s and :ref:`GridMap`\ s. The overlapping body's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. @@ -737,7 +743,7 @@ For performance reasons (collisions are all processed at the same time) this lis .. rst-class:: classref-method -:ref:`bool` **has_overlapping_areas**\ (\ ) |const| +:ref:`bool` **has_overlapping_areas**\ (\ ) |const| :ref:`🔗` Returns ``true`` if intersecting any **Area3D**\ s, otherwise returns ``false``. The overlapping area's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. @@ -751,7 +757,7 @@ For performance reasons (collisions are all processed at the same time) the list .. rst-class:: classref-method -:ref:`bool` **has_overlapping_bodies**\ (\ ) |const| +:ref:`bool` **has_overlapping_bodies**\ (\ ) |const| :ref:`🔗` Returns ``true`` if intersecting any :ref:`PhysicsBody3D`\ s or :ref:`GridMap`\ s, otherwise returns ``false``. The overlapping body's :ref:`CollisionObject3D.collision_layer` must be part of this area's :ref:`CollisionObject3D.collision_mask` in order to be detected. @@ -765,7 +771,7 @@ For performance reasons (collisions are all processed at the same time) the list .. rst-class:: classref-method -:ref:`bool` **overlaps_area**\ (\ area\: :ref:`Node`\ ) |const| +:ref:`bool` **overlaps_area**\ (\ area\: :ref:`Node`\ ) |const| :ref:`🔗` Returns ``true`` if the given **Area3D** intersects or overlaps this **Area3D**, ``false`` otherwise. @@ -779,7 +785,7 @@ Returns ``true`` if the given **Area3D** intersects or overlaps this **Area3D**, .. rst-class:: classref-method -:ref:`bool` **overlaps_body**\ (\ body\: :ref:`Node`\ ) |const| +:ref:`bool` **overlaps_body**\ (\ body\: :ref:`Node`\ ) |const| :ref:`🔗` Returns ``true`` if the given physics body intersects or overlaps this **Area3D**, ``false`` otherwise. @@ -788,6 +794,7 @@ Returns ``true`` if the given physics body intersects or overlaps this **Area3D* The ``body`` argument can either be a :ref:`PhysicsBody3D` or a :ref:`GridMap` instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_array.rst b/classes/class_array.rst index 842fc9eec20..7e85ad4b311 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -17,57 +17,41 @@ A built-in data structure that holds a sequence of elements. Description ----------- -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:**\ +An array data structure that can contain a sequence of elements of any :ref:`Variant` 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.). .. tabs:: .. code-tab:: gdscript - var array = ["One", 2, 3, "Four"] - print(array[0]) # One. - print(array[2]) # 3. - print(array[-1]) # Four. - array[2] = "Three" - print(array[-2]) # Three. - - .. code-tab:: csharp - - var array = new Godot.Collections.Array{"One", 2, 3, "Four"}; - GD.Print(array[0]); // One. - GD.Print(array[2]); // 3. - GD.Print(array[array.Count - 1]); // Four. - array[2] = "Three"; - GD.Print(array[array.Count - 2]); // Three. + var array = ["First", 2, 3, "Last"] + print(array[0]) # Prints "First" + print(array[2]) # Prints 3 + print(array[-1]) # Prints "Last" - - -Arrays can be concatenated using the ``+`` operator: - - -.. tabs:: - - .. code-tab:: gdscript - - var array1 = ["One", 2] - var array2 = [3, "Four"] - print(array1 + array2) # ["One", 2, 3, "Four"] + array[1] = "Second" + print(array[1]) # Prints "Second" + print(array[-3]) # Prints "Second" .. code-tab:: csharp - // Array concatenation is not possible with C# arrays, but is with Godot.Collections.Array. - var array1 = new Godot.Collections.Array{"One", 2}; - var array2 = new Godot.Collections.Array{3, "Four"}; - GD.Print(array1 + array2); // Prints [One, 2, 3, Four] + Godot.Collections.Array array = ["First", 2, 3, "Last"]; + GD.Print(array[0]); // Prints "First" + GD.Print(array[2]); // Prints 3 + GD.Print(array[^1]); // Prints "Last" + + array[1] = "Second"; + GD.Print(array[1]); // Prints "Second" + GD.Print(array[^3]); // Prints "Second" -\ **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:** 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. +\ **Differences between packed arrays, typed arrays, and untyped arrays:** Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. :ref:`PackedInt64Array` versus ``Array[int]``). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as :ref:`map()`. Typed arrays are in turn faster to iterate on and modify than untyped arrays. + .. note:: There are notable differences when using this API with C#. See :ref:`doc_c_sharp_differences` for more information. @@ -105,6 +89,8 @@ Constructors +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedVector3Array`\ ) | +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`Array`\ (\ from\: :ref:`PackedVector4Array`\ ) | + +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -137,6 +123,8 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`duplicate`\ (\ deep\: :ref:`bool` = false\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array` | :ref:`duplicate_deep`\ (\ deep_subresources_mode\: :ref:`int` = 1\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`erase`\ (\ value\: :ref:`Variant`\ ) | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`fill`\ (\ value\: :ref:`Variant`\ ) | @@ -145,8 +133,12 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`find`\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`find_custom`\ (\ method\: :ref:`Callable`, from\: :ref:`int` = 0\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`front`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_typed_builtin`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`get_typed_class_name`\ (\ ) |const| | @@ -197,6 +189,10 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rfind`\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rfind_custom`\ (\ method\: :ref:`Callable`, from\: :ref:`int` = -1\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set`\ (\ index\: :ref:`int`, value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`shuffle`\ (\ ) | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`size`\ (\ ) |const| | @@ -247,7 +243,7 @@ Constructor Descriptions .. rst-class:: classref-constructor -:ref:`Array` **Array**\ (\ ) +:ref:`Array` **Array**\ (\ ) :ref:`🔗` Constructs an empty **Array**. @@ -259,7 +255,41 @@ Constructs an empty **Array**. :ref:`Array` **Array**\ (\ base\: :ref:`Array`, type\: :ref:`int`, class_name\: :ref:`StringName`, script\: :ref:`Variant`\ ) -Creates a typed array from the ``base`` array. +Creates a typed array from the ``base`` array. A typed array can only contain elements of the given type, or that inherit from the given class, as described by this constructor's parameters: + +- ``type`` is the built-in :ref:`Variant` type, as one the :ref:`Variant.Type` constants. + +- ``class_name`` is the built-in class name (see :ref:`Object.get_class()`). + +- ``script`` is the associated script. It must be a :ref:`Script` instance or ``null``. + +If ``type`` is not :ref:`@GlobalScope.TYPE_OBJECT`, ``class_name`` must be an empty :ref:`StringName` and ``script`` must be ``null``. + +:: + + class_name Sword + extends Node + + class Stats: + pass + + func _ready(): + var a = Array([], TYPE_INT, "", null) # Array[int] + var b = Array([], TYPE_OBJECT, "Node", null) # Array[Node] + var c = Array([], TYPE_OBJECT, "Node", Sword) # Array[Sword] + var d = Array([], TYPE_OBJECT, "RefCounted", Stats) # Array[Stats] + +The ``base`` array's elements are converted when necessary. If this is not possible or ``base`` is already typed, this constructor fails and returns an empty **Array**. + +In GDScript, this constructor is usually not necessary, as it is possible to create a typed array through static typing: + +:: + + var numbers: Array[float] = [] + var children: Array[Node] = [$Node, $Sprite2D, $RigidBody3D] + + var integers: Array[int] = [0.2, 4.5, -2.0] + print(integers) # Prints [0, 4, -2] .. rst-class:: classref-item-separator @@ -269,7 +299,7 @@ Creates a typed array from the ``base`` array. :ref:`Array` **Array**\ (\ from\: :ref:`Array`\ ) -Returns the same array as ``from``. If you need a copy of the array, use :ref:`duplicate`. +Returns the same array as ``from``. If you need a copy of the array, use :ref:`duplicate()`. .. rst-class:: classref-item-separator @@ -361,6 +391,16 @@ Constructs an array from a :ref:`PackedVector2Array`. Constructs an array from a :ref:`PackedVector3Array`. +.. rst-class:: classref-item-separator + +---- + +.. rst-class:: classref-constructor + +:ref:`Array` **Array**\ (\ from\: :ref:`PackedVector4Array`\ ) + +Constructs an array from a :ref:`PackedVector4Array`. + .. rst-class:: classref-section-separator ---- @@ -374,28 +414,56 @@ Method Descriptions .. rst-class:: classref-method -:ref:`bool` **all**\ (\ method\: :ref:`Callable`\ ) |const| +:ref:`bool` **all**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *all* elements in the array. If the :ref:`Callable` returns ``false`` for one array element or more, this method returns ``false``. +Calls the given :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *all* elements in the array. If the :ref:`Callable` returns ``false`` for one array element or more, this method returns ``false``. -The callable's method should take one :ref:`Variant` parameter (the current array element) and return a boolean value. +The ``method`` should take one :ref:`Variant` parameter (the current array element) and return a :ref:`bool`. -:: - func _ready(): - print([6, 10, 6].all(greater_than_5)) # Prints True (3/3 elements evaluate to `true`). - print([4, 10, 4].all(greater_than_5)) # Prints False (1/3 elements evaluate to `true`). - print([4, 4, 4].all(greater_than_5)) # Prints False (0/3 elements evaluate to `true`). - print([].all(greater_than_5)) # Prints True (0/0 elements evaluate to `true`). - - print([6, 10, 6].all(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function. - +.. tabs:: + + .. code-tab:: gdscript + func greater_than_5(number): return number > 5 -See also :ref:`any`, :ref:`filter`, :ref:`map` and :ref:`reduce`. + func _ready(): + print([6, 10, 6].all(greater_than_5)) # Prints true (3/3 elements evaluate to true). + print([4, 10, 4].all(greater_than_5)) # Prints false (1/3 elements evaluate to true). + print([4, 4, 4].all(greater_than_5)) # Prints false (0/3 elements evaluate to true). + print([].all(greater_than_5)) # Prints true (0/0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].all(func(element): return element > 5)) # Prints true + + .. code-tab:: csharp + + private static bool GreaterThan5(int number) + { + return number > 5; + } + + public override void _Ready() + { + // Prints True (3/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5)); + // Prints False (1/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5)); + // Prints False (0/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5)); + // Prints True (0/0 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5)); + + // Same as the first line above, but using a lambda function. + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints True + } + + -\ **Note:** Unlike relying on the size of an array returned by :ref:`filter`, this method will return as early as possible to improve performance (especially with large arrays). +See also :ref:`any()`, :ref:`filter()`, :ref:`map()` and :ref:`reduce()`. + +\ **Note:** Unlike relying on the size of an array returned by :ref:`filter()`, this method will return as early as possible to improve performance (especially with large arrays). \ **Note:** For an empty array, this method `always `__ returns ``true``. @@ -407,28 +475,29 @@ See also :ref:`any`, :ref:`filter` **any**\ (\ method\: :ref:`Callable`\ ) |const| +:ref:`bool` **any**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *one or more* elements in the array. If the :ref:`Callable` returns ``false`` for all elements in the array, this method returns ``false``. +Calls the given :ref:`Callable` on each element in the array and returns ``true`` if the :ref:`Callable` returns ``true`` for *one or more* elements in the array. If the :ref:`Callable` returns ``false`` for all elements in the array, this method returns ``false``. -The callable's method should take one :ref:`Variant` parameter (the current array element) and return a boolean value. +The ``method`` should take one :ref:`Variant` parameter (the current array element) and return a :ref:`bool`. :: - func _ready(): - print([6, 10, 6].any(greater_than_5)) # Prints True (3 elements evaluate to `true`). - print([4, 10, 4].any(greater_than_5)) # Prints True (1 elements evaluate to `true`). - print([4, 4, 4].any(greater_than_5)) # Prints False (0 elements evaluate to `true`). - print([].any(greater_than_5)) # Prints False (0 elements evaluate to `true`). - - print([6, 10, 6].any(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function. - func greater_than_5(number): return number > 5 -See also :ref:`all`, :ref:`filter`, :ref:`map` and :ref:`reduce`. + func _ready(): + print([6, 10, 6].any(greater_than_5)) # Prints true (3 elements evaluate to true). + print([4, 10, 4].any(greater_than_5)) # Prints true (1 elements evaluate to true). + print([4, 4, 4].any(greater_than_5)) # Prints false (0 elements evaluate to true). + print([].any(greater_than_5)) # Prints false (0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].any(func(number): return number > 5)) # Prints true -\ **Note:** Unlike relying on the size of an array returned by :ref:`filter`, this method will return as early as possible to improve performance (especially with large arrays). +See also :ref:`all()`, :ref:`filter()`, :ref:`map()` and :ref:`reduce()`. + +\ **Note:** Unlike relying on the size of an array returned by :ref:`filter()`, this method will return as early as possible to improve performance (especially with large arrays). \ **Note:** For an empty array, this method always returns ``false``. @@ -440,9 +509,9 @@ See also :ref:`all`, :ref:`filter`\ ) +|void| **append**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` -Appends an element at the end of the array (alias of :ref:`push_back`). +Appends ``value`` at the end of the array (alias of :ref:`push_back()`). .. rst-class:: classref-item-separator @@ -452,16 +521,16 @@ Appends an element at the end of the array (alias of :ref:`push_back`\ ) +|void| **append_array**\ (\ array\: :ref:`Array`\ ) :ref:`🔗` -Appends another array at the end of this array. +Appends another ``array`` at the end of this array. :: - var array1 = [1, 2, 3] - var array2 = [4, 5, 6] - array1.append_array(array2) - print(array1) # Prints [1, 2, 3, 4, 5, 6]. + var numbers = [1, 2, 3] + var extra = [4, 5, 6] + numbers.append_array(extra) + print(numbers) # Prints [1, 2, 3, 4, 5, 6] .. rst-class:: classref-item-separator @@ -471,7 +540,7 @@ Appends another array at the end of this array. .. rst-class:: classref-method -|void| **assign**\ (\ array\: :ref:`Array`\ ) +|void| **assign**\ (\ array\: :ref:`Array`\ ) :ref:`🔗` Assigns elements of another ``array`` into the array. Resizes the array to match ``array``. Performs type conversions if the array is typed. @@ -483,11 +552,11 @@ Assigns elements of another ``array`` into the array. Resizes the array to match .. rst-class:: classref-method -:ref:`Variant` **back**\ (\ ) |const| +:ref:`Variant` **back**\ (\ ) |const| :ref:`🔗` -Returns the last element of the array. Prints an error and returns ``null`` if the array is empty. +Returns the last element of the array. If the array is empty, fails and returns ``null``. See also :ref:`front()`. -\ **Note:** Calling this function is not the same as writing ``array[-1]``. If the array is empty, accessing by index will pause project execution when running from the editor. +\ **Note:** Unlike with the ``[]`` operator (``array[-1]``), an error is generated without stopping project execution. .. rst-class:: classref-item-separator @@ -497,11 +566,25 @@ Returns the last element of the array. Prints an error and returns ``null`` if t .. rst-class:: classref-method -:ref:`int` **bsearch**\ (\ value\: :ref:`Variant`, before\: :ref:`bool` = true\ ) |const| +:ref:`int` **bsearch**\ (\ value\: :ref:`Variant`, before\: :ref:`bool` = true\ ) |const| :ref:`🔗` + +Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted. The algorithm used is `binary search `__. + +If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array. + +:: + + var numbers = [2, 4, 8, 10] + var idx = numbers.bsearch(7) + + numbers.insert(idx, 7) + print(numbers) # Prints [2, 4, 7, 8, 10] -Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. + var fruits = ["Apple", "Lemon", "Lemon", "Orange"] + print(fruits.bsearch("Lemon", true)) # Prints 1, points at the first "Lemon". + print(fruits.bsearch("Lemon", false)) # Prints 3, points at "Orange". -\ **Note:** Calling :ref:`bsearch` on an unsorted array results in unexpected behavior. +\ **Note:** Calling :ref:`bsearch()` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort()` before calling this method. .. rst-class:: classref-item-separator @@ -511,11 +594,36 @@ Finds the index of an existing value (or the insertion index that maintains sort .. rst-class:: classref-method -:ref:`int` **bsearch_custom**\ (\ value\: :ref:`Variant`, func\: :ref:`Callable`, before\: :ref:`bool` = true\ ) |const| +:ref:`int` **bsearch_custom**\ (\ value\: :ref:`Variant`, func\: :ref:`Callable`, before\: :ref:`bool` = true\ ) |const| :ref:`🔗` -Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a ``before`` specifier can be passed. If ``false``, the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return ``true`` if the first argument is less than the second, and return ``false`` otherwise. +Returns the index of ``value`` in the sorted array. If it cannot be found, returns where ``value`` should be inserted to keep the array sorted (using ``func`` for the comparisons). The algorithm used is `binary search `__. -\ **Note:** Calling :ref:`bsearch_custom` on an unsorted array results in unexpected behavior. +Similar to :ref:`sort_custom()`, ``func`` is called as many times as necessary, receiving one array element and ``value`` as arguments. The function should return ``true`` if the array element should be *behind* ``value``, otherwise it should return ``false``. + +If ``before`` is ``true`` (as by default), the returned index comes before all existing elements equal to ``value`` in the array. + +:: + + func sort_by_amount(a, b): + if a[1] < b[1]: + return true + return false + + func _ready(): + var my_items = [["Tomato", 2], ["Kiwi", 5], ["Rice", 9]] + + var apple = ["Apple", 5] + # "Apple" is inserted before "Kiwi". + my_items.insert(my_items.bsearch_custom(apple, sort_by_amount, true), apple) + + var banana = ["Banana", 5] + # "Banana" is inserted after "Kiwi". + my_items.insert(my_items.bsearch_custom(banana, sort_by_amount, false), banana) + + # Prints [["Tomato", 2], ["Apple", 5], ["Kiwi", 5], ["Banana", 5], ["Rice", 9]] + print(my_items) + +\ **Note:** Calling :ref:`bsearch_custom()` on an *unsorted* array will result in unexpected behavior. Use :ref:`sort_custom()` with ``func`` before calling this method. .. rst-class:: classref-item-separator @@ -525,9 +633,9 @@ Finds the index of an existing value (or the insertion index that maintains sort .. rst-class:: classref-method -|void| **clear**\ (\ ) +|void| **clear**\ (\ ) :ref:`🔗` -Clears the array. This is equivalent to using :ref:`resize` with a size of ``0``. +Removes all elements from the array. This is equivalent to using :ref:`resize()` with a size of ``0``. .. rst-class:: classref-item-separator @@ -537,10 +645,12 @@ Clears the array. This is equivalent to using :ref:`resize` **count**\ (\ value\: :ref:`Variant`\ ) |const| +:ref:`int` **count**\ (\ value\: :ref:`Variant`\ ) |const| :ref:`🔗` Returns the number of times an element is in the array. +To count how many elements in an array satisfy a condition, see :ref:`reduce()`. + .. rst-class:: classref-item-separator ---- @@ -549,29 +659,43 @@ Returns the number of times an element is in the array. .. rst-class:: classref-method -:ref:`Array` **duplicate**\ (\ deep\: :ref:`bool` = false\ ) |const| +:ref:`Array` **duplicate**\ (\ deep\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns a new copy of the array. -Returns a copy of the array. +By default, a **shallow** copy is returned: all nested **Array**, :ref:`Dictionary`, and :ref:`Resource` elements are shared with the original array. Modifying any of those in one array will also affect them in the other. -If ``deep`` is ``true``, a deep copy is performed: all nested arrays and dictionaries are duplicated and will not be shared with the original array. If ``false``, a shallow copy is made and references to the original nested arrays and dictionaries are kept, so that modifying a sub-array or dictionary in the copy will also impact those referenced in the source array. Note that any :ref:`Object`-derived elements will be shallow copied regardless of the ``deep`` setting. +If ``deep`` is ``true``, a **deep** copy is returned: all nested arrays and dictionaries are also duplicated (recursively). Any :ref:`Resource` is still shared with the original array, though. .. rst-class:: classref-item-separator ---- -.. _class_Array_method_erase: +.. _class_Array_method_duplicate_deep: .. rst-class:: classref-method -|void| **erase**\ (\ value\: :ref:`Variant`\ ) +:ref:`Array` **duplicate_deep**\ (\ deep_subresources_mode\: :ref:`int` = 1\ ) |const| :ref:`🔗` -Removes the first occurrence of a value from the array. If the value does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at` instead. +Duplicates this array, deeply, like :ref:`duplicate()`\ ``(true)``, with extra control over how subresources are handled. -\ **Note:** This method acts in-place and doesn't return a modified array. +\ ``deep_subresources_mode`` must be one of the values from :ref:`DeepDuplicateMode`. By default, only internal resources will be duplicated (recursively). -\ **Note:** On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed. +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_erase: + +.. rst-class:: classref-method + +|void| **erase**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` -\ **Note:** Do not erase entries while iterating over the array. +Finds and removes the first occurrence of ``value`` from the array. If ``value`` does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at()` instead. + +\ **Note:** This method shifts every element's index after the removed ``value`` back, which may have a noticeable performance cost, especially on larger arrays. + +\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. .. rst-class:: classref-item-separator @@ -581,9 +705,11 @@ Removes the first occurrence of a value from the array. If the value does not ex .. rst-class:: classref-method -|void| **fill**\ (\ value\: :ref:`Variant`\ ) +|void| **fill**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` + +Assigns the given ``value`` to all elements in the array. -Assigns the given value to all elements in the array. This can typically be used together with :ref:`resize` to create an array with a given size and initialized elements: +This method can often be combined with :ref:`resize()` to create an array with a given size and initialized elements: .. tabs:: @@ -591,18 +717,20 @@ Assigns the given value to all elements in the array. This can typically be used .. code-tab:: gdscript var array = [] - array.resize(10) - array.fill(0) # Initialize the 10 elements to 0. + array.resize(5) + array.fill(2) + print(array) # Prints [2, 2, 2, 2, 2] .. code-tab:: csharp - var array = new Godot.Collections.Array(); - array.Resize(10); - array.Fill(0); // Initialize the 10 elements to 0. + Godot.Collections.Array array = []; + array.Resize(5); + array.Fill(2); + GD.Print(array); // Prints [2, 2, 2, 2, 2] -\ **Note:** If ``value`` is of a reference type (:ref:`Object`-derived, **Array**, :ref:`Dictionary`, etc.) then the array is filled with the references to the same object, i.e. no duplicates are created. +\ **Note:** If ``value`` is a :ref:`Variant` passed by reference (:ref:`Object`-derived, **Array**, :ref:`Dictionary`, etc.), the array will be filled with references to the same ``value``, which are not duplicates. .. rst-class:: classref-item-separator @@ -612,22 +740,24 @@ Assigns the given value to all elements in the array. This can typically be used .. rst-class:: classref-method -:ref:`Array` **filter**\ (\ method\: :ref:`Callable`\ ) |const| +:ref:`Array` **filter**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` on each element in the array and returns a new array with the elements for which the method returned ``true``. +Calls the given :ref:`Callable` on each element in the array and returns a new, filtered **Array**. -The callable's method should take one :ref:`Variant` parameter (the current array element) and return a boolean value. +The ``method`` receives one of the array elements as an argument, and should return ``true`` to add the element to the filtered array, or ``false`` to exclude it. :: + func is_even(number): + return number % 2 == 0 + func _ready(): - print([1, 2, 3].filter(remove_1)) # Prints [2, 3]. - print([1, 2, 3].filter(func(number): return number != 1)) # Same as above, but using lambda function. - - func remove_1(number): - return number != 1 + print([1, 4, 5, 8].filter(is_even)) # Prints [4, 8] + + # Same as above, but using a lambda function. + print([1, 4, 5, 8].filter(func(number): return number % 2 == 0)) -See also :ref:`any`, :ref:`all`, :ref:`map` and :ref:`reduce`. +See also :ref:`any()`, :ref:`all()`, :ref:`map()` and :ref:`reduce()`. .. rst-class:: classref-item-separator @@ -637,115 +767,149 @@ See also :ref:`any`, :ref:`all`, .. rst-class:: classref-method -:ref:`int` **find**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| +:ref:`int` **find**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| :ref:`🔗` + +Returns the index of the **first** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array. -Searches the array for a value and returns its index or ``-1`` if not found. Optionally, the initial search index can be passed. +\ **Note:** If you just want to know whether the array contains ``what``, use :ref:`has()` (``Contains`` in C#). In GDScript, you may also use the ``in`` operator. + +\ **Note:** For performance reasons, the search is affected by ``what``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. .. rst-class:: classref-item-separator ---- -.. _class_Array_method_front: +.. _class_Array_method_find_custom: .. rst-class:: classref-method -:ref:`Variant` **front**\ (\ ) |const| +:ref:`int` **find_custom**\ (\ method\: :ref:`Callable`, from\: :ref:`int` = 0\ ) |const| :ref:`🔗` + +Returns the index of the **first** element in the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array. + +\ ``method`` is a callable that takes an element of the array, and returns a :ref:`bool`. + +\ **Note:** If you just want to know whether the array contains *anything* that satisfies ``method``, use :ref:`any()`. + + +.. tabs:: + + .. code-tab:: gdscript + + func is_even(number): + return number % 2 == 0 + + func _ready(): + print([1, 3, 4, 7].find_custom(is_even.bind())) # Prints 2 -Returns the first element of the array. Prints an error and returns ``null`` if the array is empty. -\ **Note:** Calling this function is not the same as writing ``array[0]``. If the array is empty, accessing by index will pause project execution when running from the editor. .. rst-class:: classref-item-separator ---- -.. _class_Array_method_get_typed_builtin: +.. _class_Array_method_front: .. rst-class:: classref-method -:ref:`int` **get_typed_builtin**\ (\ ) |const| +:ref:`Variant` **front**\ (\ ) |const| :ref:`🔗` -Returns the :ref:`Variant.Type` constant for a typed array. If the **Array** is not typed, returns :ref:`@GlobalScope.TYPE_NIL`. +Returns the first element of the array. If the array is empty, fails and returns ``null``. See also :ref:`back()`. + +\ **Note:** Unlike with the ``[]`` operator (``array[0]``), an error is generated without stopping project execution. .. rst-class:: classref-item-separator ---- -.. _class_Array_method_get_typed_class_name: +.. _class_Array_method_get: .. rst-class:: classref-method -:ref:`StringName` **get_typed_class_name**\ (\ ) |const| +:ref:`Variant` **get**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` -Returns a class name of a typed **Array** of type :ref:`@GlobalScope.TYPE_OBJECT`. +Returns the element at the given ``index`` in the array. If ``index`` out-of-bounds or negative, this method fails and returns ``null``. + +This method is similar (but not identical) to the ``[]`` operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor. .. rst-class:: classref-item-separator ---- -.. _class_Array_method_get_typed_script: +.. _class_Array_method_get_typed_builtin: .. rst-class:: classref-method -:ref:`Variant` **get_typed_script**\ (\ ) |const| +:ref:`int` **get_typed_builtin**\ (\ ) |const| :ref:`🔗` -Returns the script associated with a typed array tied to a class name. +Returns the built-in :ref:`Variant` type of the typed array as a :ref:`Variant.Type` constant. If the array is not typed, returns :ref:`@GlobalScope.TYPE_NIL`. See also :ref:`is_typed()`. .. rst-class:: classref-item-separator ---- -.. _class_Array_method_has: +.. _class_Array_method_get_typed_class_name: .. rst-class:: classref-method -:ref:`bool` **has**\ (\ value\: :ref:`Variant`\ ) |const| +:ref:`StringName` **get_typed_class_name**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the array contains the given value. +Returns the **built-in** class name of the typed array, if the built-in :ref:`Variant` type :ref:`@GlobalScope.TYPE_OBJECT`. Otherwise, returns an empty :ref:`StringName`. See also :ref:`is_typed()` and :ref:`Object.get_class()`. +.. rst-class:: classref-item-separator -.. tabs:: +---- - .. code-tab:: gdscript +.. _class_Array_method_get_typed_script: - print(["inside", 7].has("inside")) # True - print(["inside", 7].has("outside")) # False - print(["inside", 7].has(7)) # True - print(["inside", 7].has("7")) # False +.. rst-class:: classref-method - .. code-tab:: csharp +:ref:`Variant` **get_typed_script**\ (\ ) |const| :ref:`🔗` + +Returns the :ref:`Script` instance associated with this typed array, or ``null`` if it does not exist. See also :ref:`is_typed()`. - var arr = new Godot.Collections.Array { "inside", 7 }; - // has is renamed to Contains - GD.Print(arr.Contains("inside")); // True - GD.Print(arr.Contains("outside")); // False - GD.Print(arr.Contains(7)); // True - GD.Print(arr.Contains("7")); // False +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_has: +.. rst-class:: classref-method +:ref:`bool` **has**\ (\ value\: :ref:`Variant`\ ) |const| :ref:`🔗` -\ **Note:** This is equivalent to using the ``in`` operator as follows: +Returns ``true`` if the array contains the given ``value``. .. tabs:: .. code-tab:: gdscript - # Will evaluate to `true`. - if 2 in [2, 4, 6, 8]: - print("Contains!") + print(["inside", 7].has("inside")) # Prints true + print(["inside", 7].has("outside")) # Prints false + print(["inside", 7].has(7)) # Prints true + print(["inside", 7].has("7")) # Prints false .. code-tab:: csharp - // As there is no "in" keyword in C#, you have to use Contains - var array = new Godot.Collections.Array { 2, 4, 6, 8 }; - if (array.Contains(2)) - { - GD.Print("Contains!"); - } + Godot.Collections.Array arr = ["inside", 7]; + // By C# convention, this method is renamed to `Contains`. + GD.Print(arr.Contains("inside")); // Prints True + GD.Print(arr.Contains("outside")); // Prints False + GD.Print(arr.Contains(7)); // Prints True + GD.Print(arr.Contains("7")); // Prints False +In GDScript, this is equivalent to the ``in`` operator: + +:: + + if 4 in [2, 4, 6, 8]: + print("4 is here!") # Will be printed. + +\ **Note:** For performance reasons, the search is affected by the ``value``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. + .. rst-class:: classref-item-separator ---- @@ -754,11 +918,11 @@ Returns ``true`` if the array contains the given value. .. rst-class:: classref-method -:ref:`int` **hash**\ (\ ) |const| +:ref:`int` **hash**\ (\ ) |const| :ref:`🔗` Returns a hashed 32-bit integer value representing the array and its contents. -\ **Note:** **Array**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the arrays are equal, because different arrays can have identical hash values due to hash collisions. +\ **Note:** Arrays with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the countrary, arrays with different hash values are guaranteed to be different. .. rst-class:: classref-item-separator @@ -768,13 +932,13 @@ Returns a hashed 32-bit integer value representing the array and its contents. .. rst-class:: classref-method -:ref:`int` **insert**\ (\ position\: :ref:`int`, value\: :ref:`Variant`\ ) +:ref:`int` **insert**\ (\ position\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` -Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (``pos == size()``). Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. +Inserts a new element (``value``) at a given index (``position``) in the array. ``position`` should be between ``0`` and the array's :ref:`size()`. If negative, ``position`` is considered relative to the end of the array. -\ **Note:** This method acts in-place and doesn't return a modified array. +Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` constants if this method fails. -\ **Note:** On large arrays, this method will be slower if the inserted element is close to the beginning of the array (index 0). This is because all elements placed after the newly inserted element have to be reindexed. +\ **Note:** Every element's index after ``position`` needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -784,9 +948,9 @@ Inserts a new element at a given position in the array. The position must be val .. rst-class:: classref-method -:ref:`bool` **is_empty**\ (\ ) |const| +:ref:`bool` **is_empty**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the array is empty. +Returns ``true`` if the array is empty (``[]``). See also :ref:`size()`. .. rst-class:: classref-item-separator @@ -796,9 +960,11 @@ Returns ``true`` if the array is empty. .. rst-class:: classref-method -:ref:`bool` **is_read_only**\ (\ ) |const| +:ref:`bool` **is_read_only**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the array is read-only. See :ref:`make_read_only()`. -Returns ``true`` if the array is read-only. See :ref:`make_read_only`. Arrays are automatically read-only if declared with ``const`` keyword. +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. .. rst-class:: classref-item-separator @@ -808,9 +974,9 @@ Returns ``true`` if the array is read-only. See :ref:`make_read_only` **is_same_typed**\ (\ array\: :ref:`Array`\ ) |const| +:ref:`bool` **is_same_typed**\ (\ array\: :ref:`Array`\ ) |const| :ref:`🔗` -Returns ``true`` if the array is typed the same as ``array``. +Returns ``true`` if this array is typed the same as the given ``array``. See also :ref:`is_typed()`. .. rst-class:: classref-item-separator @@ -820,9 +986,16 @@ Returns ``true`` if the array is typed the same as ``array``. .. rst-class:: classref-method -:ref:`bool` **is_typed**\ (\ ) |const| +:ref:`bool` **is_typed**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the array is typed. Typed arrays can only contain elements of a specific type, as defined by the typed array constructor. The methods of a typed array are still expected to return a generic :ref:`Variant`. -Returns ``true`` if the array is typed. Typed arrays can only store elements of their associated type and provide type safety for the ``[]`` operator. Methods of typed array still return :ref:`Variant`. +In GDScript, it is possible to define a typed array with static typing: + +:: + + var numbers: Array[float] = [0.2, 4.2, -2.0] + print(numbers.is_typed()) # Prints true .. rst-class:: classref-item-separator @@ -832,9 +1005,11 @@ Returns ``true`` if the array is typed. Typed arrays can only store elements of .. rst-class:: classref-method -|void| **make_read_only**\ (\ ) +|void| **make_read_only**\ (\ ) :ref:`🔗` + +Makes the array read-only. The array's elements cannot be overridden with different values, and their order cannot change. Does not apply to nested elements, such as dictionaries. -Makes the array read-only, i.e. disabled modifying of the array's elements. Does not apply to nested content, e.g. content of nested arrays. +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. .. rst-class:: classref-item-separator @@ -844,22 +1019,24 @@ Makes the array read-only, i.e. disabled modifying of the array's elements. Does .. rst-class:: classref-method -:ref:`Array` **map**\ (\ method\: :ref:`Callable`\ ) |const| +:ref:`Array` **map**\ (\ method\: :ref:`Callable`\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` for each element in the array and returns a new array filled with values returned by the method. +Calls the given :ref:`Callable` for each element in the array and returns a new array filled with values returned by the ``method``. -The callable's method should take one :ref:`Variant` parameter (the current array element) and can return any :ref:`Variant`. +The ``method`` should take one :ref:`Variant` parameter (the current array element) and can return any :ref:`Variant`. :: + func double(number): + return number * 2 + func _ready(): - print([1, 2, 3].map(negate)) # Prints [-1, -2, -3]. - print([1, 2, 3].map(func(number): return -number)) # Same as above, but using lambda function. - - func negate(number): - return -number + print([1, 2, 3].map(double)) # Prints [2, 4, 6] + + # Same as above, but using a lambda function. + print([1, 2, 3].map(func(element): return element * 2)) -See also :ref:`filter`, :ref:`reduce`, :ref:`any` and :ref:`all`. +See also :ref:`filter()`, :ref:`reduce()`, :ref:`any()` and :ref:`all()`. .. rst-class:: classref-item-separator @@ -869,21 +1046,11 @@ See also :ref:`filter`, :ref:`reduce` **max**\ (\ ) |const| +:ref:`Variant` **max**\ (\ ) |const| :ref:`🔗` -Returns the maximum value contained in the array if all elements are of comparable types. If the elements can't be compared, ``null`` is returned. +Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`min()`. -To find the maximum value using a custom comparator, you can use :ref:`reduce`. In this example every array element is checked and the first maximum value is returned: - -:: - - func _ready(): - var arr = [Vector2(0, 1), Vector2(2, 0), Vector2(1, 1), Vector2(1, 0), Vector2(0, 2)] - # In this example we compare the lengths. - print(arr.reduce(func(max, val): return val if is_length_greater(val, max) else max)) - - func is_length_greater(a, b): - return a.length() > b.length() +To find the maximum value using a custom comparator, you can use :ref:`reduce()`. .. rst-class:: classref-item-separator @@ -893,11 +1060,9 @@ To find the maximum value using a custom comparator, you can use :ref:`reduce` **min**\ (\ ) |const| +:ref:`Variant` **min**\ (\ ) |const| :ref:`🔗` -Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, ``null`` is returned. - -See also :ref:`max` for an example of using a custom comparator. +Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also :ref:`max()`. .. rst-class:: classref-item-separator @@ -907,24 +1072,26 @@ See also :ref:`max` for an example of using a custom com .. rst-class:: classref-method -:ref:`Variant` **pick_random**\ (\ ) |const| +:ref:`Variant` **pick_random**\ (\ ) |const| :ref:`🔗` -Returns a random value from the target array. Prints an error and returns ``null`` if the array is empty. +Returns a random element from the array. Generates an error and returns ``null`` if the array is empty. .. tabs:: .. code-tab:: gdscript - var array: Array[int] = [1, 2, 3, 4] - print(array.pick_random()) # Prints either of the four numbers. + # May print 1, 2, 3.25, or "Hi". + print([1, 2, 3.25, "Hi"].pick_random()) .. code-tab:: csharp - var array = new Godot.Collections.Array { 1, 2, 3, 4 }; - GD.Print(array.PickRandom()); // Prints either of the four numbers. + Godot.Collections.Array array = [1, 2, 3.25f, "Hi"]; + GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi". + +\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi()` or :ref:`shuffle()`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed()`. .. rst-class:: classref-item-separator @@ -934,11 +1101,11 @@ Returns a random value from the target array. Prints an error and returns ``null .. rst-class:: classref-method -:ref:`Variant` **pop_at**\ (\ position\: :ref:`int`\ ) +:ref:`Variant` **pop_at**\ (\ position\: :ref:`int`\ ) :ref:`🔗` -Removes and returns the element of the array at index ``position``. If negative, ``position`` is considered relative to the end of the array. Leaves the array unchanged and returns ``null`` if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty. +Removes and returns the element of the array at index ``position``. If negative, ``position`` is considered relative to the end of the array. Returns ``null`` if the array is empty. If ``position`` is out of bounds, an error message is also generated. -\ **Note:** On large arrays, this method can be slower than :ref:`pop_back` as it will reindex the array's elements that are located after the removed element. The larger the array and the lower the index of the removed element, the slower :ref:`pop_at` will be. +\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -948,9 +1115,9 @@ Removes and returns the element of the array at index ``position``. If negative, .. rst-class:: classref-method -:ref:`Variant` **pop_back**\ (\ ) +:ref:`Variant` **pop_back**\ (\ ) :ref:`🔗` -Removes and returns the last element of the array. Returns ``null`` if the array is empty, without printing an error message. See also :ref:`pop_front`. +Removes and returns the last element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_front()`. .. rst-class:: classref-item-separator @@ -960,11 +1127,11 @@ Removes and returns the last element of the array. Returns ``null`` if the array .. rst-class:: classref-method -:ref:`Variant` **pop_front**\ (\ ) +:ref:`Variant` **pop_front**\ (\ ) :ref:`🔗` -Removes and returns the first element of the array. Returns ``null`` if the array is empty, without printing an error message. See also :ref:`pop_back`. +Removes and returns the first element of the array. Returns ``null`` if the array is empty, without generating an error. See also :ref:`pop_back()`. -\ **Note:** On large arrays, this method is much slower than :ref:`pop_back` as it will reindex all the array's elements every time it's called. The larger the array, the slower :ref:`pop_front` will be. +\ **Note:** This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -974,9 +1141,9 @@ Removes and returns the first element of the array. Returns ``null`` if the arra .. rst-class:: classref-method -|void| **push_back**\ (\ value\: :ref:`Variant`\ ) +|void| **push_back**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` -Appends an element at the end of the array. See also :ref:`push_front`. +Appends an element at the end of the array. See also :ref:`push_front()`. .. rst-class:: classref-item-separator @@ -986,11 +1153,11 @@ Appends an element at the end of the array. See also :ref:`push_front`\ ) +|void| **push_front**\ (\ value\: :ref:`Variant`\ ) :ref:`🔗` -Adds an element at the beginning of the array. See also :ref:`push_back`. +Adds an element at the beginning of the array. See also :ref:`push_back()`. -\ **Note:** On large arrays, this method is much slower than :ref:`push_back` as it will reindex all the array's elements every time it's called. The larger the array, the slower :ref:`push_front` will be. +\ **Note:** This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays. .. rst-class:: classref-item-separator @@ -1000,22 +1167,51 @@ Adds an element at the beginning of the array. See also :ref:`push_back` **reduce**\ (\ method\: :ref:`Callable`, accum\: :ref:`Variant` = null\ ) |const| +:ref:`Variant` **reduce**\ (\ method\: :ref:`Callable`, accum\: :ref:`Variant` = null\ ) |const| :ref:`🔗` -Calls the provided :ref:`Callable` for each element in array and accumulates the result in ``accum``. +Calls the given :ref:`Callable` for each element in array, accumulates the result in ``accum``, then returns it. -The callable's method takes two arguments: the current value of ``accum`` and the current array element. If ``accum`` is ``null`` (default value), the iteration will start from the second element, with the first one used as initial value of ``accum``. +The ``method`` takes two arguments: the current value of ``accum`` and the current array element. If ``accum`` is ``null`` (as by default), the iteration will start from the second element, with the first one used as initial value of ``accum``. :: - func _ready(): - print([1, 2, 3].reduce(sum, 10)) # Prints 16. - print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) # Same as above, but using lambda function. - func sum(accum, number): return accum + number -See also :ref:`map`, :ref:`filter`, :ref:`any` and :ref:`all`. + func _ready(): + print([1, 2, 3].reduce(sum, 0)) # Prints 6 + print([1, 2, 3].reduce(sum, 10)) # Prints 16 + + # Same as above, but using a lambda function. + print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) + +If :ref:`max()` is not desirable, this method may also be used to implement a custom comparator: + +:: + + func _ready(): + var arr = [Vector2i(5, 0), Vector2i(3, 4), Vector2i(1, 2)] + + var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max) + print(longest_vec) # Prints (3, 4) + + func is_length_greater(a, b): + return a.length() > b.length() + +This method can also be used to count how many elements in an array satisfy a certain condition, similar to :ref:`count()`: + +:: + + func is_even(number): + return number % 2 == 0 + + func _ready(): + var arr = [1, 2, 3, 4, 5] + # If the current element is even, increment count, otherwise leave count the same. + var even_count = arr.reduce(func(count, next): return count + 1 if is_even(next) else count, 0) + print(even_count) # Prints 2 + +See also :ref:`map()`, :ref:`filter()`, :ref:`any()`, and :ref:`all()`. .. rst-class:: classref-item-separator @@ -1025,15 +1221,15 @@ See also :ref:`map`, :ref:`filter`\ ) +|void| **remove_at**\ (\ position\: :ref:`int`\ ) :ref:`🔗` -Removes an element from the array by index. If the index does not exist in the array, nothing happens. To remove an element by searching for its value, use :ref:`erase` instead. +Removes the element from the array at the given index (``position``). If the index is out of bounds, this method fails. If the index is negative, ``position`` is considered relative to the end of the array. -\ **Note:** This method acts in-place and doesn't return a modified array. +If you need to return the removed element, use :ref:`pop_at()`. To remove an element by value, use :ref:`erase()` instead. -\ **Note:** On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed. +\ **Note:** This method shifts every element's index after ``position`` back, which may have a noticeable performance cost, especially on larger arrays. -\ **Note:** ``position`` cannot be negative. To remove an element relative to the end of the array, use ``arr.remove_at(arr.size() - (i + 1))``. To remove the last element from the array without returning the value, use ``arr.resize(arr.size() - 1)``. +\ **Note:** The ``position`` cannot be negative. To remove an element relative to the end of the array, use ``arr.remove_at(arr.size() - (i + 1))``. To remove the last element from the array, use ``arr.resize(arr.size() - 1)``. .. rst-class:: classref-item-separator @@ -1043,13 +1239,13 @@ Removes an element from the array by index. If the index does not exist in the a .. rst-class:: classref-method -:ref:`int` **resize**\ (\ size\: :ref:`int`\ ) +:ref:`int` **resize**\ (\ size\: :ref:`int`\ ) :ref:`🔗` -Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``. Returns :ref:`@GlobalScope.OK` on success, or one of the other :ref:`Error` values if the operation failed. +Sets the array's number of elements to ``size``. If ``size`` is smaller than the array's current size, the elements at the end are removed. If ``size`` is greater, new default elements (usually ``null``) are added, depending on the array's type. -Calling :ref:`resize` once and assigning the new values is faster than adding new elements one by one. +Returns :ref:`@GlobalScope.OK` on success, or one of the following :ref:`Error` constants if this method fails: :ref:`@GlobalScope.ERR_LOCKED` if the array is read-only, :ref:`@GlobalScope.ERR_INVALID_PARAMETER` if the size is negative, or :ref:`@GlobalScope.ERR_OUT_OF_MEMORY` if allocations fail. Use :ref:`size()` to find the actual size of the array after resize. -\ **Note:** This method acts in-place and doesn't return a modified array. +\ **Note:** Calling this method once and assigning the new values is faster than calling :ref:`append()` for every new element. .. rst-class:: classref-item-separator @@ -1059,9 +1255,9 @@ Calling :ref:`resize` once and assigning the new valu .. rst-class:: classref-method -|void| **reverse**\ (\ ) +|void| **reverse**\ (\ ) :ref:`🔗` -Reverses the order of the elements in the array. +Reverses the order of all elements in the array. .. rst-class:: classref-item-separator @@ -1071,9 +1267,33 @@ Reverses the order of the elements in the array. .. rst-class:: classref-method -:ref:`int` **rfind**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| +:ref:`int` **rfind**\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| :ref:`🔗` + +Returns the index of the **last** occurrence of ``what`` in this array, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_rfind_custom: + +.. rst-class:: classref-method + +:ref:`int` **rfind_custom**\ (\ method\: :ref:`Callable`, from\: :ref:`int` = -1\ ) |const| :ref:`🔗` + +Returns the index of the **last** element of the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find_custom()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_set: + +.. rst-class:: classref-method + +|void| **set**\ (\ index\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`🔗` -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. +Sets the value of the element at the given ``index`` to the given ``value``. This will not change the size of the array, it only changes the value at an index already in the array. This is the same as using the ``[]`` operator (``array[index] = value``). .. rst-class:: classref-item-separator @@ -1083,9 +1303,11 @@ Searches the array in reverse order. Optionally, a start search index can be pas .. rst-class:: classref-method -|void| **shuffle**\ (\ ) +|void| **shuffle**\ (\ ) :ref:`🔗` -Shuffles the array such that the items will have a random order. This method uses the global random number generator common to methods such as :ref:`@GlobalScope.randi`. Call :ref:`@GlobalScope.randomize` to ensure that a new seed will be used each time if you want non-reproducible shuffling. +Shuffles all elements of the array in a random order. + +\ **Note:** Like many similar functions in the engine (such as :ref:`@GlobalScope.randi()` or :ref:`pick_random()`), this method uses a common, global random seed. To get a predictable outcome from this method, see :ref:`@GlobalScope.seed()`. .. rst-class:: classref-item-separator @@ -1095,9 +1317,9 @@ Shuffles the array such that the items will have a random order. This method use .. rst-class:: classref-method -:ref:`int` **size**\ (\ ) |const| +:ref:`int` **size**\ (\ ) |const| :ref:`🔗` -Returns the number of elements in the array. +Returns the number of elements in the array. Empty arrays (``[]``) always return ``0``. See also :ref:`is_empty()`. .. rst-class:: classref-item-separator @@ -1107,19 +1329,26 @@ Returns the number of elements in the array. .. rst-class:: classref-method -:ref:`Array` **slice**\ (\ begin\: :ref:`int`, end\: :ref:`int` = 2147483647, step\: :ref:`int` = 1, deep\: :ref:`bool` = false\ ) |const| +:ref:`Array` **slice**\ (\ begin\: :ref:`int`, end\: :ref:`int` = 2147483647, step\: :ref:`int` = 1, deep\: :ref:`bool` = false\ ) |const| :ref:`🔗` -Returns the slice of the **Array**, from ``begin`` (inclusive) to ``end`` (exclusive), as a new **Array**. +Returns a new **Array** containing this array's elements, from index ``begin`` (inclusive) to ``end`` (exclusive), every ``step`` elements. -The absolute value of ``begin`` and ``end`` will be clamped to the array size, so the default value for ``end`` makes it slice to the size of the array by default (i.e. ``arr.slice(1)`` is a shorthand for ``arr.slice(1, arr.size())``). +If either ``begin`` or ``end`` are negative, their value is relative to the end of the array. -If either ``begin`` or ``end`` are negative, they will be relative to the end of the array (i.e. ``arr.slice(0, -2)`` is a shorthand for ``arr.slice(0, arr.size() - 2)``). +If ``step`` is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, ``begin`` must be greater than ``end``. -If specified, ``step`` is the relative index between source elements. It can be negative, then ``begin`` must be higher than ``end``. For example, ``[0, 1, 2, 3, 4, 5].slice(5, 1, -2)`` returns ``[5, 3]``. +If ``deep`` is ``true``, all nested **Array** and :ref:`Dictionary` elements in the slice are duplicated from the original, recursively. See also :ref:`duplicate()`. -If ``deep`` is true, each element will be copied by value rather than by reference. +:: -\ **Note:** To include the first element when ``step`` is negative, use ``arr.slice(begin, -arr.size() - 1, step)`` (i.e. ``[0, 1, 2].slice(1, -4, -1)`` returns ``[1, 0]``). + var letters = ["A", "B", "C", "D", "E", "F"] + + print(letters.slice(0, 2)) # Prints ["A", "B"] + print(letters.slice(2, -2)) # Prints ["C", "D"] + print(letters.slice(-2, 6)) # Prints ["E", "F"] + + print(letters.slice(0, 6, 2)) # Prints ["A", "C", "E"] + print(letters.slice(4, 1, -1)) # Prints ["E", "D", "C"] .. rst-class:: classref-item-separator @@ -1129,38 +1358,28 @@ If ``deep`` is true, each element will be copied by value rather than by referen .. rst-class:: classref-method -|void| **sort**\ (\ ) - -Sorts the array. - -\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when using :ref:`sort`. +|void| **sort**\ (\ ) :ref:`🔗` -\ **Note:** Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example: +Sorts the array in ascending order. The final order is dependent on the "less than" (``<``) comparison between elements. .. tabs:: .. code-tab:: gdscript - var strings = ["string1", "string2", "string10", "string11"] - strings.sort() - print(strings) # Prints [string1, string10, string11, string2] + var numbers = [10, 5, 2.5, 8] + numbers.sort() + print(numbers) # Prints [2.5, 5, 8, 10] .. code-tab:: csharp - var strings = new Godot.Collections.Array { "string1", "string2", "string10", "string11" }; - strings.Sort(); - GD.Print(strings); // Prints [string1, string10, string11, string2] + Godot.Collections.Array numbers = [10, 5, 2.5, 8]; + numbers.Sort(); + GD.Print(numbers); // Prints [2.5, 5, 8, 10] -To perform natural order sorting, you can use :ref:`sort_custom` with :ref:`String.naturalnocasecmp_to` as follows: - -:: - - var strings = ["string1", "string2", "string10", "string11"] - strings.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) - print(strings) # Prints [string1, string2, string10, string11] +\ **Note:** The sorting algorithm used is not `stable `__. This means that equivalent elements (such as ``2`` and ``2.0``) may have their order changed when calling :ref:`sort()`. .. rst-class:: classref-item-separator @@ -1170,38 +1389,41 @@ To perform natural order sorting, you can use :ref:`sort_custom`\ ) +|void| **sort_custom**\ (\ func\: :ref:`Callable`\ ) :ref:`🔗` -Sorts the array using a custom method. The custom method receives two arguments (a pair of elements from the array) and must return either ``true`` or ``false``. For two elements ``a`` and ``b``, if the given method returns ``true``, element ``b`` will be after element ``a`` in the array. +Sorts the array using a custom :ref:`Callable`. -\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when using :ref:`sort_custom`. +\ ``func`` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *before* the second one, otherwise it should return ``false``. -\ **Note:** You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior. - - -.. tabs:: - - .. code-tab:: gdscript +:: func sort_ascending(a, b): - if a[0] < b[0]: + if a[1] < b[1]: return true return false - + func _ready(): - var my_items = [[5, "Potato"], [9, "Rice"], [4, "Tomato"]] + var my_items = [["Tomato", 5], ["Apple", 9], ["Rice", 4]] my_items.sort_custom(sort_ascending) - print(my_items) # Prints [[4, Tomato], [5, Potato], [9, Rice]]. - - # Descending, lambda version. - my_items.sort_custom(func(a, b): return a[0] > b[0]) - print(my_items) # Prints [[9, Rice], [5, Potato], [4, Tomato]]. + print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]] - .. code-tab:: csharp + # Sort descending, using a lambda function. + my_items.sort_custom(func(a, b): return a[1] > b[1]) + print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]] - // There is no custom sort support for Godot.Collections.Array +It may also be necessary to use this method to sort strings by natural order, with :ref:`String.naturalnocasecmp_to()`, as in the following example: +:: + + var files = ["newfile1", "newfile2", "newfile10", "newfile11"] + files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) + print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"] + +\ **Note:** In C#, this method is not supported. + +\ **Note:** The sorting algorithm used is not `stable `__. This means that values considered equal may have their order changed when calling this method. +\ **Note:** You should not randomize the return value of ``func``, as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior. .. rst-class:: classref-section-separator @@ -1216,9 +1438,9 @@ Operator Descriptions .. rst-class:: classref-operator -:ref:`bool` **operator !=**\ (\ right\: :ref:`Array`\ ) +:ref:`bool` **operator !=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Compares the left operand **Array** against the ``right`` **Array**. Returns ``true`` if the sizes or contents of the arrays are *not* equal, ``false`` otherwise. +Returns ``true`` if the array's size or its elements are different than ``right``'s. .. rst-class:: classref-item-separator @@ -1228,9 +1450,29 @@ Compares the left operand **Array** against the ``right`` **Array**. Returns ``t .. rst-class:: classref-operator -:ref:`Array` **operator +**\ (\ right\: :ref:`Array`\ ) +:ref:`Array` **operator +**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Appends the ``right`` array to the left operand, creating a new **Array**. This is also known as an array concatenation. + + +.. tabs:: + + .. code-tab:: gdscript + + var array1 = ["One", 2] + var array2 = [3, "Four"] + print(array1 + array2) # Prints ["One", 2, 3, "Four"] + + .. code-tab:: csharp -Concatenates two **Array**\ s together, with the ``right`` **Array** being added to the end of the **Array** specified in the left operand. For example, ``[1, 2] + [3, 4]`` results in ``[1, 2, 3, 4]``. + // Note that concatenation is not possible with C#'s native Array type. + Godot.Collections.Array array1 = ["One", 2]; + Godot.Collections.Array array2 = [3, "Four"]; + GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"] + + + +\ **Note:** For existing arrays, :ref:`append_array()` is much more efficient than concatenation and assignment with the ``+=`` operator. .. rst-class:: classref-item-separator @@ -1240,9 +1482,11 @@ Concatenates two **Array**\ s together, with the ``right`` **Array** being added .. rst-class:: classref-operator -:ref:`bool` **operator <**\ (\ right\: :ref:`Array`\ ) +:ref:`bool` **operator <**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair. -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is less, or ``false`` if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``false`` if the left operand **Array** has fewer elements, otherwise it returns ``true``. +If all searched elements are equal, returns ``true`` if this array's size is less than ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1252,9 +1496,11 @@ Performs a comparison for each index between the left operand **Array** and the .. rst-class:: classref-operator -:ref:`bool` **operator <=**\ (\ right\: :ref:`Array`\ ) +:ref:`bool` **operator <=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is less, or ``false`` if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``true`` if the left operand **Array** has the same number of elements or fewer, otherwise it returns ``false``. +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than ``right``'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less or equal to ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1264,7 +1510,7 @@ Performs a comparison for each index between the left operand **Array** and the .. rst-class:: classref-operator -:ref:`bool` **operator ==**\ (\ right\: :ref:`Array`\ ) +:ref:`bool` **operator ==**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` Compares the left operand **Array** against the ``right`` **Array**. Returns ``true`` if the sizes and contents of the arrays are equal, ``false`` otherwise. @@ -1276,9 +1522,11 @@ Compares the left operand **Array** against the ``right`` **Array**. Returns ``t .. rst-class:: classref-operator -:ref:`bool` **operator >**\ (\ right\: :ref:`Array`\ ) +:ref:`bool` **operator >**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair. -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is greater, or ``false`` if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``true`` if the ``right`` **Array** has more elements, otherwise it returns ``false``. +If all searched elements are equal, returns ``true`` if this array's size is greater than ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1288,9 +1536,11 @@ Performs a comparison for each index between the left operand **Array** and the .. rst-class:: classref-operator -:ref:`bool` **operator >=**\ (\ right\: :ref:`Array`\ ) +:ref:`bool` **operator >=**\ (\ right\: :ref:`Array`\ ) :ref:`🔗` + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than ``right``'s, ``false`` if this element is less. Otherwise, continues to the next pair. -Performs a comparison for each index between the left operand **Array** and the ``right`` **Array**, considering the highest common index of both arrays for this comparison: Returns ``true`` on the first occurrence of an element that is greater, or ``false`` if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns ``true`` if the ``right`` **Array** has more or the same number of elements, otherwise it returns ``false``. +If all searched elements are equal, returns ``true`` if this array's size is greater or equal to ``right``'s, otherwise returns ``false``. .. rst-class:: classref-item-separator @@ -1300,11 +1550,12 @@ Performs a comparison for each index between the left operand **Array** and the .. rst-class:: classref-operator -:ref:`Variant` **operator []**\ (\ index\: :ref:`int`\ ) +:ref:`Variant` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` -Returns a reference to the element of type :ref:`Variant` at the specified location. Arrays start at index 0. ``index`` can be a zero or positive value to start from the beginning, or a negative value to start from the end. Out-of-bounds array access causes a run-time error, which will result in an error being printed and the project execution pausing if run from the editor. +Returns the :ref:`Variant` element at the specified ``index``. Arrays start at index 0. If ``index`` is greater or equal to ``0``, the element is fetched starting from the beginning of the array. If ``index`` is a negative value, the element is fetched starting from the end. Accessing an array out-of-bounds will cause a run-time error, pausing the project execution if run from the editor. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_arraymesh.rst b/classes/class_arraymesh.rst index e79c0a38efc..ff27ab5bbba 100644 --- a/classes/class_arraymesh.rst +++ b/classes/class_arraymesh.rst @@ -32,13 +32,13 @@ The most basic example is the creation of a single triangle: vertices.push_back(Vector3(0, 1, 0)) vertices.push_back(Vector3(1, 0, 0)) vertices.push_back(Vector3(0, 0, 1)) - + # Initialize the ArrayMesh. var arr_mesh = ArrayMesh.new() var arrays = [] arrays.resize(Mesh.ARRAY_MAX) arrays[Mesh.ARRAY_VERTEX] = vertices - + # Create the Mesh. arr_mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays) var m = MeshInstance3D.new() @@ -46,19 +46,19 @@ The most basic example is the creation of a single triangle: .. code-tab:: csharp - var vertices = new Vector3[] - { + Vector3[] vertices = + [ new Vector3(0, 1, 0), new Vector3(1, 0, 0), new Vector3(0, 0, 1), - }; - + ]; + // Initialize the ArrayMesh. var arrMesh = new ArrayMesh(); - var arrays = new Godot.Collections.Array(); + Godot.Collections.Array arrays = []; arrays.Resize((int)Mesh.ArrayType.Max); arrays[(int)Mesh.ArrayType.Vertex] = vertices; - + // Create the Mesh. arrMesh.AddSurfaceFromArrays(Mesh.PrimitiveType.Triangles, arrays); var m = new MeshInstance3D(); @@ -134,6 +134,8 @@ Methods +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PrimitiveType` | :ref:`surface_get_primitive_type`\ (\ surf_idx\: :ref:`int`\ ) |const| | +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`surface_remove`\ (\ surf_idx\: :ref:`int`\ ) | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`surface_set_name`\ (\ surf_idx\: :ref:`int`, name\: :ref:`String`\ ) | +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`surface_update_attribute_region`\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) | @@ -156,14 +158,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`BlendShapeMode` **blend_shape_mode** = ``1`` +:ref:`BlendShapeMode` **blend_shape_mode** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_blend_shape_mode**\ (\ value\: :ref:`BlendShapeMode`\ ) - :ref:`BlendShapeMode` **get_blend_shape_mode**\ (\ ) -Sets the blend shape mode to one of :ref:`BlendShapeMode`. +The blend shape mode. .. rst-class:: classref-item-separator @@ -173,7 +175,7 @@ Sets the blend shape mode to one of :ref:`BlendShapeMode` **custom_aabb** = ``AABB(0, 0, 0, 0, 0, 0)`` +:ref:`AABB` **custom_aabb** = ``AABB(0, 0, 0, 0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -190,14 +192,16 @@ Overrides the :ref:`AABB` with one defined by user for use with frus .. rst-class:: classref-property -:ref:`ArrayMesh` **shadow_mesh** +:ref:`ArrayMesh` **shadow_mesh** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_shadow_mesh**\ (\ value\: :ref:`ArrayMesh`\ ) - :ref:`ArrayMesh` **get_shadow_mesh**\ (\ ) -An optional mesh which is used for rendering shadows and can be used for the depth prepass. Can be used to increase performance of shadow rendering by using a mesh that only contains vertex position data (without normals, UVs, colors, etc.). +An optional mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.). + +\ **Note:** This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly. .. rst-class:: classref-section-separator @@ -212,9 +216,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_blend_shape**\ (\ name\: :ref:`StringName`\ ) +|void| **add_blend_shape**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` -Adds name for a blend shape that will be added with :ref:`add_surface_from_arrays`. Must be called before surface is added. +Adds name for a blend shape that will be added with :ref:`add_surface_from_arrays()`. Must be called before surface is added. .. rst-class:: classref-item-separator @@ -224,9 +228,9 @@ Adds name for a blend shape that will be added with :ref:`add_surface_from_array .. rst-class:: classref-method -|void| **add_surface_from_arrays**\ (\ primitive\: :ref:`PrimitiveType`, arrays\: :ref:`Array`, blend_shapes\: :ref:`Array`\[:ref:`Array`\] = [], lods\: :ref:`Dictionary` = {}, flags\: |bitfield|\[:ref:`ArrayFormat`\] = 0\ ) +|void| **add_surface_from_arrays**\ (\ primitive\: :ref:`PrimitiveType`, arrays\: :ref:`Array`, blend_shapes\: :ref:`Array`\[:ref:`Array`\] = [], lods\: :ref:`Dictionary` = {}, flags\: |bitfield|\[:ref:`ArrayFormat`\] = 0\ ) :ref:`🔗` -Creates a new surface. :ref:`Mesh.get_surface_count` will become the ``surf_idx`` for this new surface. +Creates a new surface. :ref:`Mesh.get_surface_count()` will become the ``surf_idx`` for this new surface. Surfaces are created to be rendered using a ``primitive``, which may be any of the values defined in :ref:`PrimitiveType`. @@ -234,9 +238,9 @@ The ``arrays`` argument is an array of arrays. Each of the :ref:`Mesh.ARRAY_MAX< The ``blend_shapes`` argument is an array of vertex data for each blend shape. Each element is an array of the same structure as ``arrays``, but :ref:`Mesh.ARRAY_VERTEX`, :ref:`Mesh.ARRAY_NORMAL`, and :ref:`Mesh.ARRAY_TANGENT` are set if and only if they are set in ``arrays`` and all other entries are ``null``. -The ``lods`` argument is a dictionary with :ref:`float` keys and :ref:`PackedInt32Array` values. Each entry in the dictionary represents a LOD level of the surface, where the value is the :ref:`Mesh.ARRAY_INDEX` array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of a LOD also increases the distance that the objects has to be from the camera before the LOD is used. +The ``lods`` argument is a dictionary with :ref:`float` keys and :ref:`PackedInt32Array` values. Each entry in the dictionary represents an LOD level of the surface, where the value is the :ref:`Mesh.ARRAY_INDEX` array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used. -The ``flags`` argument is the bitwise or of, as required: One value of :ref:`ArrayCustomFormat` left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, :ref:`Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE`, :ref:`Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS`, or :ref:`Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY`. +The ``flags`` argument is the bitwise OR of, as required: One value of :ref:`ArrayCustomFormat` left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, :ref:`Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE`, :ref:`Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS`, or :ref:`Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY`. \ **Note:** When using indices, it is recommended to only use points, lines, or triangles. @@ -248,7 +252,7 @@ The ``flags`` argument is the bitwise or of, as required: One value of :ref:`Arr .. rst-class:: classref-method -|void| **clear_blend_shapes**\ (\ ) +|void| **clear_blend_shapes**\ (\ ) :ref:`🔗` Removes all blend shapes from this **ArrayMesh**. @@ -260,7 +264,7 @@ Removes all blend shapes from this **ArrayMesh**. .. rst-class:: classref-method -|void| **clear_surfaces**\ (\ ) +|void| **clear_surfaces**\ (\ ) :ref:`🔗` Removes all surfaces from this **ArrayMesh**. @@ -272,7 +276,7 @@ Removes all surfaces from this **ArrayMesh**. .. rst-class:: classref-method -:ref:`int` **get_blend_shape_count**\ (\ ) |const| +:ref:`int` **get_blend_shape_count**\ (\ ) |const| :ref:`🔗` Returns the number of blend shapes that the **ArrayMesh** holds. @@ -284,7 +288,7 @@ Returns the number of blend shapes that the **ArrayMesh** holds. .. rst-class:: classref-method -:ref:`StringName` **get_blend_shape_name**\ (\ index\: :ref:`int`\ ) |const| +:ref:`StringName` **get_blend_shape_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the name of the blend shape at this index. @@ -296,7 +300,7 @@ Returns the name of the blend shape at this index. .. rst-class:: classref-method -:ref:`Error` **lightmap_unwrap**\ (\ transform\: :ref:`Transform3D`, texel_size\: :ref:`float`\ ) +:ref:`Error` **lightmap_unwrap**\ (\ transform\: :ref:`Transform3D`, texel_size\: :ref:`float`\ ) :ref:`🔗` Performs a UV unwrap on the **ArrayMesh** to prepare the mesh for lightmapping. @@ -308,7 +312,7 @@ Performs a UV unwrap on the **ArrayMesh** to prepare the mesh for lightmapping. .. rst-class:: classref-method -|void| **regen_normal_maps**\ (\ ) +|void| **regen_normal_maps**\ (\ ) :ref:`🔗` Regenerates tangents for each of the **ArrayMesh**'s surfaces. @@ -320,7 +324,7 @@ Regenerates tangents for each of the **ArrayMesh**'s surfaces. .. rst-class:: classref-method -|void| **set_blend_shape_name**\ (\ index\: :ref:`int`, name\: :ref:`StringName`\ ) +|void| **set_blend_shape_name**\ (\ index\: :ref:`int`, name\: :ref:`StringName`\ ) :ref:`🔗` Sets the name of the blend shape at this index. @@ -332,7 +336,7 @@ Sets the name of the blend shape at this index. .. rst-class:: classref-method -:ref:`int` **surface_find_by_name**\ (\ name\: :ref:`String`\ ) |const| +:ref:`int` **surface_find_by_name**\ (\ name\: :ref:`String`\ ) |const| :ref:`🔗` Returns the index of the first surface with this name held within this **ArrayMesh**. If none are found, -1 is returned. @@ -344,9 +348,9 @@ Returns the index of the first surface with this name held within this **ArrayMe .. rst-class:: classref-method -:ref:`int` **surface_get_array_index_len**\ (\ surf_idx\: :ref:`int`\ ) |const| +:ref:`int` **surface_get_array_index_len**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the length in indices of the index array in the requested surface (see :ref:`add_surface_from_arrays`). +Returns the length in indices of the index array in the requested surface (see :ref:`add_surface_from_arrays()`). .. rst-class:: classref-item-separator @@ -356,9 +360,9 @@ Returns the length in indices of the index array in the requested surface (see : .. rst-class:: classref-method -:ref:`int` **surface_get_array_len**\ (\ surf_idx\: :ref:`int`\ ) |const| +:ref:`int` **surface_get_array_len**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the length in vertices of the vertex array in the requested surface (see :ref:`add_surface_from_arrays`). +Returns the length in vertices of the vertex array in the requested surface (see :ref:`add_surface_from_arrays()`). .. rst-class:: classref-item-separator @@ -368,9 +372,9 @@ Returns the length in vertices of the vertex array in the requested surface (see .. rst-class:: classref-method -|bitfield|\[:ref:`ArrayFormat`\] **surface_get_format**\ (\ surf_idx\: :ref:`int`\ ) |const| +|bitfield|\[:ref:`ArrayFormat`\] **surface_get_format**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` -Returns the format mask of the requested surface (see :ref:`add_surface_from_arrays`). +Returns the format mask of the requested surface (see :ref:`add_surface_from_arrays()`). .. rst-class:: classref-item-separator @@ -380,7 +384,7 @@ Returns the format mask of the requested surface (see :ref:`add_surface_from_arr .. rst-class:: classref-method -:ref:`String` **surface_get_name**\ (\ surf_idx\: :ref:`int`\ ) |const| +:ref:`String` **surface_get_name**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` Gets the name assigned to this surface. @@ -392,9 +396,21 @@ Gets the name assigned to this surface. .. rst-class:: classref-method -:ref:`PrimitiveType` **surface_get_primitive_type**\ (\ surf_idx\: :ref:`int`\ ) |const| +:ref:`PrimitiveType` **surface_get_primitive_type**\ (\ surf_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the primitive type of the requested surface (see :ref:`add_surface_from_arrays()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_ArrayMesh_method_surface_remove: + +.. rst-class:: classref-method + +|void| **surface_remove**\ (\ surf_idx\: :ref:`int`\ ) :ref:`🔗` -Returns the primitive type of the requested surface (see :ref:`add_surface_from_arrays`). +Removes the surface at the given index from the Mesh, shifting surfaces with higher index down by one. .. rst-class:: classref-item-separator @@ -404,7 +420,7 @@ Returns the primitive type of the requested surface (see :ref:`add_surface_from_ .. rst-class:: classref-method -|void| **surface_set_name**\ (\ surf_idx\: :ref:`int`, name\: :ref:`String`\ ) +|void| **surface_set_name**\ (\ surf_idx\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` Sets a name for a given surface. @@ -416,7 +432,7 @@ Sets a name for a given surface. .. rst-class:: classref-method -|void| **surface_update_attribute_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) +|void| **surface_update_attribute_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) :ref:`🔗` .. container:: contribute @@ -430,7 +446,7 @@ Sets a name for a given surface. .. rst-class:: classref-method -|void| **surface_update_skin_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) +|void| **surface_update_skin_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) :ref:`🔗` .. container:: contribute @@ -444,13 +460,14 @@ Sets a name for a given surface. .. rst-class:: classref-method -|void| **surface_update_vertex_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) +|void| **surface_update_vertex_region**\ (\ surf_idx\: :ref:`int`, offset\: :ref:`int`, data\: :ref:`PackedByteArray`\ ) :ref:`🔗` .. container:: contribute There is currently no description for this method. Please help us by :ref:`contributing one `! .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_arrayoccluder3d.rst b/classes/class_arrayoccluder3d.rst index c9c3c4cf625..24daff7388c 100644 --- a/classes/class_arrayoccluder3d.rst +++ b/classes/class_arrayoccluder3d.rst @@ -69,7 +69,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`PackedInt32Array` **indices** = ``PackedInt32Array()`` +:ref:`PackedInt32Array` **indices** = ``PackedInt32Array()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -78,7 +78,9 @@ Property Descriptions The occluder's index position. Indices determine which points from the :ref:`vertices` array should be drawn, and in which order. -\ **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. +\ **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. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedInt32Array` for more details. .. rst-class:: classref-item-separator @@ -88,7 +90,7 @@ The occluder's index position. Indices determine which points from the :ref:`ver .. rst-class:: classref-property -:ref:`PackedVector3Array` **vertices** = ``PackedVector3Array()`` +:ref:`PackedVector3Array` **vertices** = ``PackedVector3Array()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -97,7 +99,9 @@ The occluder's index position. Indices determine which points from the :ref:`ver The occluder's vertex positions in local 3D coordinates. -\ **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. +\ **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. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector3Array` for more details. .. rst-class:: classref-section-separator @@ -112,11 +116,12 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_arrays**\ (\ vertices\: :ref:`PackedVector3Array`, indices\: :ref:`PackedInt32Array`\ ) +|void| **set_arrays**\ (\ vertices\: :ref:`PackedVector3Array`, indices\: :ref:`PackedInt32Array`\ ) :ref:`🔗` 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.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_aspectratiocontainer.rst b/classes/class_aspectratiocontainer.rst index a90d06e74c9..d606f09adfd 100644 --- a/classes/class_aspectratiocontainer.rst +++ b/classes/class_aspectratiocontainer.rst @@ -59,7 +59,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **StretchMode**: +enum **StretchMode**: :ref:`🔗` .. _class_AspectRatioContainer_constant_STRETCH_WIDTH_CONTROLS_HEIGHT: @@ -103,7 +103,7 @@ When the bounding rectangle of child controls exceed the container's size and :r .. rst-class:: classref-enumeration -enum **AlignmentMode**: +enum **AlignmentMode**: :ref:`🔗` .. _class_AspectRatioContainer_constant_ALIGNMENT_BEGIN: @@ -142,7 +142,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`AlignmentMode` **alignment_horizontal** = ``1`` +:ref:`AlignmentMode` **alignment_horizontal** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -159,7 +159,7 @@ Specifies the horizontal relative position of child controls. .. rst-class:: classref-property -:ref:`AlignmentMode` **alignment_vertical** = ``1`` +:ref:`AlignmentMode` **alignment_vertical** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -176,7 +176,7 @@ Specifies the vertical relative position of child controls. .. rst-class:: classref-property -:ref:`float` **ratio** = ``1.0`` +:ref:`float` **ratio** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -193,7 +193,7 @@ The aspect ratio to enforce on child controls. This is the width divided by the .. rst-class:: classref-property -:ref:`StretchMode` **stretch_mode** = ``2`` +:ref:`StretchMode` **stretch_mode** = ``2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -203,6 +203,7 @@ The aspect ratio to enforce on child controls. This is the width divided by the The stretch mode used to align child controls. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_astar2d.rst b/classes/class_astar2d.rst index 0692f720d0d..aad2ca6a775 100644 --- a/classes/class_astar2d.rst +++ b/classes/class_astar2d.rst @@ -23,6 +23,25 @@ An implementation of the A\* algorithm, used to find the shortest path between t 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-introduction-group + +Tutorials +--------- + +- `Grid-based Navigation with AStarGrid2D Demo `__ + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+--------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`neighbor_filter_enabled` | ``false`` | + +-------------------------+--------------------------------------------------------------------------------+-----------+ + .. rst-class:: classref-reftable-group Methods @@ -34,7 +53,9 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_filter_neighbor`\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_point`\ (\ id\: :ref:`int`, position\: :ref:`Vector2`, weight_scale\: :ref:`float` = 1.0\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -52,7 +73,7 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_closest_position_in_segment`\ (\ to_position\: :ref:`Vector2`\ ) |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedInt64Array` | :ref:`get_id_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) | + | :ref:`PackedInt64Array` | :ref:`get_id_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_point_capacity`\ (\ ) |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -62,7 +83,7 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedInt64Array` | :ref:`get_point_ids`\ (\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) | + | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`int`\ ) |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -89,6 +110,28 @@ Methods .. rst-class:: classref-descriptions-group +Property Descriptions +--------------------- + +.. _class_AStar2D_property_neighbor_filter_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **neighbor_filter_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_neighbor_filter_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_neighbor_filter_enabled**\ (\ ) + +If ``true`` enables the filtering of neighbors via :ref:`_filter_neighbor()`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- @@ -96,7 +139,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| +:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` Called when computing the cost between two connected points. @@ -110,7 +153,7 @@ Note that this function is hidden in the default **AStar2D** class. .. rst-class:: classref-method -:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` Called when estimating the cost between a point and the path's ending point. @@ -120,15 +163,29 @@ Note that this function is hidden in the default **AStar2D** class. ---- +.. _class_AStar2D_private_method__filter_neighbor: + +.. rst-class:: classref-method + +:ref:`bool` **_filter_neighbor**\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +Called when neighboring enters processing and if :ref:`neighbor_filter_enabled` is ``true``. If ``true`` is returned the point will not be processed. + +Note that this function is hidden in the default **AStar2D** class. + +.. rst-class:: classref-item-separator + +---- + .. _class_AStar2D_method_add_point: .. rst-class:: classref-method -|void| **add_point**\ (\ id\: :ref:`int`, position\: :ref:`Vector2`, weight_scale\: :ref:`float` = 1.0\ ) +|void| **add_point**\ (\ id\: :ref:`int`, position\: :ref:`Vector2`, weight_scale\: :ref:`float` = 1.0\ ) :ref:`🔗` Adds a new point at the given position with the given identifier. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 0.0 or greater. -The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost` when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower ``weight_scale``\ s to form a path. +The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower ``weight_scale``\ s to form a path. .. tabs:: @@ -155,7 +212,7 @@ If there already exists a point for the given ``id``, its position and weight sc .. rst-class:: classref-method -:ref:`bool` **are_points_connected**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| +:ref:`bool` **are_points_connected**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| :ref:`🔗` Returns whether there is a connection/segment between the given points. If ``bidirectional`` is ``false``, returns whether movement from ``id`` to ``to_id`` is possible through this segment. @@ -167,7 +224,7 @@ Returns whether there is a connection/segment between the given points. If ``bid .. rst-class:: classref-method -|void| **clear**\ (\ ) +|void| **clear**\ (\ ) :ref:`🔗` Clears all the points and segments. @@ -179,7 +236,7 @@ Clears all the points and segments. .. rst-class:: classref-method -|void| **connect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) +|void| **connect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` Creates a segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is allowed, not the reverse direction. @@ -210,7 +267,7 @@ Creates a segment between the given points. If ``bidirectional`` is ``false``, o .. rst-class:: classref-method -|void| **disconnect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) +|void| **disconnect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` Deletes the segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is prevented, and a unidirectional segment possibly remains. @@ -222,7 +279,7 @@ Deletes the segment between the given points. If ``bidirectional`` is ``false``, .. rst-class:: classref-method -:ref:`int` **get_available_point_id**\ (\ ) |const| +:ref:`int` **get_available_point_id**\ (\ ) |const| :ref:`🔗` Returns the next available point ID with no point associated to it. @@ -234,7 +291,7 @@ Returns the next available point ID with no point associated to it. .. rst-class:: classref-method -:ref:`int` **get_closest_point**\ (\ to_position\: :ref:`Vector2`, include_disabled\: :ref:`bool` = false\ ) |const| +:ref:`int` **get_closest_point**\ (\ to_position\: :ref:`Vector2`, include_disabled\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the ID of the closest point to ``to_position``, optionally taking disabled points into account. Returns ``-1`` if there are no points in the points pool. @@ -248,7 +305,7 @@ Returns the ID of the closest point to ``to_position``, optionally taking disabl .. rst-class:: classref-method -:ref:`Vector2` **get_closest_position_in_segment**\ (\ to_position\: :ref:`Vector2`\ ) |const| +:ref:`Vector2` **get_closest_position_in_segment**\ (\ to_position\: :ref:`Vector2`\ ) |const| :ref:`🔗` Returns the closest position to ``to_position`` that resides inside a segment between two connected points. @@ -283,10 +340,14 @@ The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the clo .. rst-class:: classref-method -:ref:`PackedInt64Array` **get_id_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) +:ref:`PackedInt64Array` **get_id_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + .. tabs:: @@ -297,12 +358,12 @@ Returns an array with the IDs of the points that form the path found by AStar2D astar.add_point(2, Vector2(0, 1), 1) # Default weight is 1 astar.add_point(3, Vector2(1, 1)) astar.add_point(4, Vector2(2, 0)) - + astar.connect_points(1, 2, false) astar.connect_points(2, 3, false) astar.connect_points(4, 3, false) astar.connect_points(1, 4, false) - + var res = astar.get_id_path(1, 3) # Returns [1, 2, 3] .. code-tab:: csharp @@ -312,12 +373,12 @@ Returns an array with the IDs of the points that form the path found by AStar2D astar.AddPoint(2, new Vector2(0, 1), 1); // Default weight is 1 astar.AddPoint(3, new Vector2(1, 1)); astar.AddPoint(4, new Vector2(2, 0)); - + astar.ConnectPoints(1, 2, false); astar.ConnectPoints(2, 3, false); astar.ConnectPoints(4, 3, false); astar.ConnectPoints(1, 4, false); - int[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] + long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] @@ -331,9 +392,9 @@ If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` .. rst-class:: classref-method -:ref:`int` **get_point_capacity**\ (\ ) |const| +:ref:`int` **get_point_capacity**\ (\ ) |const| :ref:`🔗` -Returns the capacity of the structure backing the points, useful in conjunction with :ref:`reserve_space`. +Returns the capacity of the structure backing the points, useful in conjunction with :ref:`reserve_space()`. .. rst-class:: classref-item-separator @@ -343,7 +404,7 @@ Returns the capacity of the structure backing the points, useful in conjunction .. rst-class:: classref-method -:ref:`PackedInt64Array` **get_point_connections**\ (\ id\: :ref:`int`\ ) +:ref:`PackedInt64Array` **get_point_connections**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Returns an array with the IDs of the points that form the connection with the given point. @@ -357,10 +418,10 @@ Returns an array with the IDs of the points that form the connection with the gi astar.add_point(2, Vector2(0, 1)) astar.add_point(3, Vector2(1, 1)) astar.add_point(4, Vector2(2, 0)) - + astar.connect_points(1, 2, true) astar.connect_points(1, 3, true) - + var neighbors = astar.get_point_connections(1) # Returns [2, 3] .. code-tab:: csharp @@ -370,11 +431,11 @@ Returns an array with the IDs of the points that form the connection with the gi astar.AddPoint(2, new Vector2(0, 1)); astar.AddPoint(3, new Vector2(1, 1)); astar.AddPoint(4, new Vector2(2, 0)); - + astar.ConnectPoints(1, 2, true); astar.ConnectPoints(1, 3, true); - - int[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] + + long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] @@ -386,7 +447,7 @@ Returns an array with the IDs of the points that form the connection with the gi .. rst-class:: classref-method -:ref:`int` **get_point_count**\ (\ ) |const| +:ref:`int` **get_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points currently in the points pool. @@ -398,7 +459,7 @@ Returns the number of points currently in the points pool. .. rst-class:: classref-method -:ref:`PackedInt64Array` **get_point_ids**\ (\ ) +:ref:`PackedInt64Array` **get_point_ids**\ (\ ) :ref:`🔗` Returns an array of all point IDs. @@ -410,11 +471,15 @@ Returns an array of all point IDs. .. rst-class:: classref-method -:ref:`PackedVector2Array` **get_point_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) +:ref:`PackedVector2Array` **get_point_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the points that are in the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. -\ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty :ref:`PackedVector2Array` and will print an error message. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty array and will print an error message. + +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. .. rst-class:: classref-item-separator @@ -424,7 +489,7 @@ Returns an array with the points that are in the path found by AStar2D between t .. rst-class:: classref-method -:ref:`Vector2` **get_point_position**\ (\ id\: :ref:`int`\ ) |const| +:ref:`Vector2` **get_point_position**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point associated with the given ``id``. @@ -436,7 +501,7 @@ Returns the position of the point associated with the given ``id``. .. rst-class:: classref-method -:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`int`\ ) |const| +:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the weight scale of the point associated with the given ``id``. @@ -448,7 +513,7 @@ Returns the weight scale of the point associated with the given ``id``. .. rst-class:: classref-method -:ref:`bool` **has_point**\ (\ id\: :ref:`int`\ ) |const| +:ref:`bool` **has_point**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether a point associated with the given ``id`` exists. @@ -460,7 +525,7 @@ Returns whether a point associated with the given ``id`` exists. .. rst-class:: classref-method -:ref:`bool` **is_point_disabled**\ (\ id\: :ref:`int`\ ) |const| +:ref:`bool` **is_point_disabled**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. @@ -472,7 +537,7 @@ Returns whether a point is disabled or not for pathfinding. By default, all poin .. rst-class:: classref-method -|void| **remove_point**\ (\ id\: :ref:`int`\ ) +|void| **remove_point**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Removes the point associated with the given ``id`` from the points pool. @@ -484,9 +549,9 @@ Removes the point associated with the given ``id`` from the points pool. .. rst-class:: classref-method -|void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) +|void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) :ref:`🔗` -Reserves space internally for ``num_nodes`` points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity. +Reserves space internally for ``num_nodes`` points. Useful if you're adding a known large number of points at once, such as points on a grid. .. rst-class:: classref-item-separator @@ -496,7 +561,7 @@ Reserves space internally for ``num_nodes`` points, useful if you're adding a kn .. rst-class:: classref-method -|void| **set_point_disabled**\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) +|void| **set_point_disabled**\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) :ref:`🔗` Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. @@ -508,7 +573,7 @@ Disables or enables the specified point for pathfinding. Useful for making a tem .. rst-class:: classref-method -|void| **set_point_position**\ (\ id\: :ref:`int`, position\: :ref:`Vector2`\ ) +|void| **set_point_position**\ (\ id\: :ref:`int`, position\: :ref:`Vector2`\ ) :ref:`🔗` Sets the ``position`` for the point with the given ``id``. @@ -520,11 +585,12 @@ Sets the ``position`` for the point with the given ``id``. .. rst-class:: classref-method -|void| **set_point_weight_scale**\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) +|void| **set_point_weight_scale**\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) :ref:`🔗` -Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost` when determining the overall cost of traveling across a segment from a neighboring point to this point. +Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_astar3d.rst b/classes/class_astar3d.rst index 8dbfca02472..11b038f6bac 100644 --- a/classes/class_astar3d.rst +++ b/classes/class_astar3d.rst @@ -21,44 +21,70 @@ Description 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`. 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`. +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. +It is also possible to use non-Euclidean distances. To do so, create a script that extends **AStar3D** and override the methods :ref:`_compute_cost()` and :ref:`_estimate_cost()`. Both should take two point IDs and return the distance between the corresponding points. + +\ **Example:** Use Manhattan distance instead of Euclidean distance: .. tabs:: .. code-tab:: gdscript - class MyAStar: - extends AStar3D - - func _compute_cost(u, v): - return abs(u - v) - - func _estimate_cost(u, v): - return min(0, abs(u - v) - 1) + class_name MyAStar3D + extends AStar3D + + func _compute_cost(u, v): + var u_pos = get_point_position(u) + var v_pos = get_point_position(v) + return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z) + + func _estimate_cost(u, v): + var u_pos = get_point_position(u) + var v_pos = get_point_position(v) + return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z) .. code-tab:: csharp - public partial class MyAStar : AStar3D + using Godot; + + [GlobalClass] + public partial class MyAStar3D : AStar3D { public override float _ComputeCost(long fromId, long toId) { - return Mathf.Abs((int)(fromId - toId)); + Vector3 fromPoint = GetPointPosition(fromId); + Vector3 toPoint = GetPointPosition(toId); + + return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z); } - + public override float _EstimateCost(long fromId, long toId) { - return Mathf.Min(0, Mathf.Abs((int)(fromId - toId)) - 1); + Vector3 fromPoint = GetPointPosition(fromId); + Vector3 toPoint = GetPointPosition(toId); + return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z); } } -\ :ref:`_estimate_cost` should return a lower bound of the distance, i.e. ``_estimate_cost(u, v) <= _compute_cost(u, v)``. This serves as a hint to the algorithm because the custom :ref:`_compute_cost` might be computation-heavy. If this is not the case, make :ref:`_estimate_cost` return the same value as :ref:`_compute_cost` to provide the algorithm with the most accurate information. +\ :ref:`_estimate_cost()` should return a lower bound of the distance, i.e. ``_estimate_cost(u, v) <= _compute_cost(u, v)``. This serves as a hint to the algorithm because the custom :ref:`_compute_cost()` might be computation-heavy. If this is not the case, make :ref:`_estimate_cost()` return the same value as :ref:`_compute_cost()` to provide the algorithm with the most accurate information. + +If the default :ref:`_estimate_cost()` and :ref:`_compute_cost()` methods are used, or if the supplied :ref:`_estimate_cost()` method returns a lower bound of the cost, then the paths returned by A\* will be the lowest-cost paths. Here, the cost of a path equals the sum of the :ref:`_compute_cost()` results of all segments in the path multiplied by the ``weight_scale``\ s of the endpoints of the respective segments. If the default methods are used and the ``weight_scale``\ s of all points are set to ``1.0``, then this equals the sum of Euclidean distances of all segments in the path. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto -If the default :ref:`_estimate_cost` and :ref:`_compute_cost` methods are used, or if the supplied :ref:`_estimate_cost` method returns a lower bound of the cost, then the paths returned by A\* will be the lowest-cost paths. Here, the cost of a path equals the sum of the :ref:`_compute_cost` results of all segments in the path multiplied by the ``weight_scale``\ s of the endpoints of the respective segments. If the default methods are used and the ``weight_scale``\ s of all points are set to ``1.0``, then this equals the sum of Euclidean distances of all segments in the path. + +-------------------------+--------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`neighbor_filter_enabled` | ``false`` | + +-------------------------+--------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group @@ -71,7 +97,9 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| | + +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_filter_neighbor`\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_point`\ (\ id\: :ref:`int`, position\: :ref:`Vector3`, weight_scale\: :ref:`float` = 1.0\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -89,7 +117,7 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`get_closest_position_in_segment`\ (\ to_position\: :ref:`Vector3`\ ) |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedInt64Array` | :ref:`get_id_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) | + | :ref:`PackedInt64Array` | :ref:`get_id_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_point_capacity`\ (\ ) |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -99,7 +127,7 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedInt64Array` | :ref:`get_point_ids`\ (\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector3Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) | + | :ref:`PackedVector3Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`get_point_position`\ (\ id\: :ref:`int`\ ) |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -126,6 +154,28 @@ Methods .. rst-class:: classref-descriptions-group +Property Descriptions +--------------------- + +.. _class_AStar3D_property_neighbor_filter_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **neighbor_filter_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_neighbor_filter_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_neighbor_filter_enabled**\ (\ ) + +If ``true`` enables the filtering of neighbors via :ref:`_filter_neighbor()`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- @@ -133,7 +183,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| +:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` Called when computing the cost between two connected points. @@ -147,7 +197,7 @@ Note that this function is hidden in the default **AStar3D** class. .. rst-class:: classref-method -:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` Called when estimating the cost between a point and the path's ending point. @@ -157,15 +207,29 @@ Note that this function is hidden in the default **AStar3D** class. ---- +.. _class_AStar3D_private_method__filter_neighbor: + +.. rst-class:: classref-method + +:ref:`bool` **_filter_neighbor**\ (\ from_id\: :ref:`int`, neighbor_id\: :ref:`int`\ ) |virtual| |const| :ref:`🔗` + +Called when neighboring point enters processing and if :ref:`neighbor_filter_enabled` is ``true``. If ``true`` is returned the point will not be processed. + +Note that this function is hidden in the default **AStar3D** class. + +.. rst-class:: classref-item-separator + +---- + .. _class_AStar3D_method_add_point: .. rst-class:: classref-method -|void| **add_point**\ (\ id\: :ref:`int`, position\: :ref:`Vector3`, weight_scale\: :ref:`float` = 1.0\ ) +|void| **add_point**\ (\ id\: :ref:`int`, position\: :ref:`Vector3`, weight_scale\: :ref:`float` = 1.0\ ) :ref:`🔗` Adds a new point at the given position with the given identifier. The ``id`` must be 0 or larger, and the ``weight_scale`` must be 0.0 or greater. -The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost` when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower ``weight_scale``\ s to form a path. +The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower ``weight_scale``\ s to form a path. .. tabs:: @@ -192,7 +256,7 @@ If there already exists a point for the given ``id``, its position and weight sc .. rst-class:: classref-method -:ref:`bool` **are_points_connected**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| +:ref:`bool` **are_points_connected**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) |const| :ref:`🔗` Returns whether the two given points are directly connected by a segment. If ``bidirectional`` is ``false``, returns whether movement from ``id`` to ``to_id`` is possible through this segment. @@ -204,7 +268,7 @@ Returns whether the two given points are directly connected by a segment. If ``b .. rst-class:: classref-method -|void| **clear**\ (\ ) +|void| **clear**\ (\ ) :ref:`🔗` Clears all the points and segments. @@ -216,7 +280,7 @@ Clears all the points and segments. .. rst-class:: classref-method -|void| **connect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) +|void| **connect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` Creates a segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is allowed, not the reverse direction. @@ -247,7 +311,7 @@ Creates a segment between the given points. If ``bidirectional`` is ``false``, o .. rst-class:: classref-method -|void| **disconnect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) +|void| **disconnect_points**\ (\ id\: :ref:`int`, to_id\: :ref:`int`, bidirectional\: :ref:`bool` = true\ ) :ref:`🔗` Deletes the segment between the given points. If ``bidirectional`` is ``false``, only movement from ``id`` to ``to_id`` is prevented, and a unidirectional segment possibly remains. @@ -259,7 +323,7 @@ Deletes the segment between the given points. If ``bidirectional`` is ``false``, .. rst-class:: classref-method -:ref:`int` **get_available_point_id**\ (\ ) |const| +:ref:`int` **get_available_point_id**\ (\ ) |const| :ref:`🔗` Returns the next available point ID with no point associated to it. @@ -271,7 +335,7 @@ Returns the next available point ID with no point associated to it. .. rst-class:: classref-method -:ref:`int` **get_closest_point**\ (\ to_position\: :ref:`Vector3`, include_disabled\: :ref:`bool` = false\ ) |const| +:ref:`int` **get_closest_point**\ (\ to_position\: :ref:`Vector3`, include_disabled\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns the ID of the closest point to ``to_position``, optionally taking disabled points into account. Returns ``-1`` if there are no points in the points pool. @@ -285,7 +349,7 @@ Returns the ID of the closest point to ``to_position``, optionally taking disabl .. rst-class:: classref-method -:ref:`Vector3` **get_closest_position_in_segment**\ (\ to_position\: :ref:`Vector3`\ ) |const| +:ref:`Vector3` **get_closest_position_in_segment**\ (\ to_position\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the closest position to ``to_position`` that resides inside a segment between two connected points. @@ -320,10 +384,14 @@ The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the clo .. rst-class:: classref-method -:ref:`PackedInt64Array` **get_id_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) +:ref:`PackedInt64Array` **get_id_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the IDs of the points that form the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + .. tabs:: @@ -334,12 +402,12 @@ Returns an array with the IDs of the points that form the path found by AStar3D astar.add_point(2, Vector3(0, 1, 0), 1) # Default weight is 1 astar.add_point(3, Vector3(1, 1, 0)) astar.add_point(4, Vector3(2, 0, 0)) - + astar.connect_points(1, 2, false) astar.connect_points(2, 3, false) astar.connect_points(4, 3, false) astar.connect_points(1, 4, false) - + var res = astar.get_id_path(1, 3) # Returns [1, 2, 3] .. code-tab:: csharp @@ -353,7 +421,7 @@ Returns an array with the IDs of the points that form the path found by AStar3D astar.ConnectPoints(2, 3, false); astar.ConnectPoints(4, 3, false); astar.ConnectPoints(1, 4, false); - int[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] + long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] @@ -367,9 +435,9 @@ If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` .. rst-class:: classref-method -:ref:`int` **get_point_capacity**\ (\ ) |const| +:ref:`int` **get_point_capacity**\ (\ ) |const| :ref:`🔗` -Returns the capacity of the structure backing the points, useful in conjunction with :ref:`reserve_space`. +Returns the capacity of the structure backing the points, useful in conjunction with :ref:`reserve_space()`. .. rst-class:: classref-item-separator @@ -379,7 +447,7 @@ Returns the capacity of the structure backing the points, useful in conjunction .. rst-class:: classref-method -:ref:`PackedInt64Array` **get_point_connections**\ (\ id\: :ref:`int`\ ) +:ref:`PackedInt64Array` **get_point_connections**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Returns an array with the IDs of the points that form the connection with the given point. @@ -393,10 +461,10 @@ Returns an array with the IDs of the points that form the connection with the gi astar.add_point(2, Vector3(0, 1, 0)) astar.add_point(3, Vector3(1, 1, 0)) astar.add_point(4, Vector3(2, 0, 0)) - + astar.connect_points(1, 2, true) astar.connect_points(1, 3, true) - + var neighbors = astar.get_point_connections(1) # Returns [2, 3] .. code-tab:: csharp @@ -408,8 +476,8 @@ Returns an array with the IDs of the points that form the connection with the gi astar.AddPoint(4, new Vector3(2, 0, 0)); astar.ConnectPoints(1, 2, true); astar.ConnectPoints(1, 3, true); - - int[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] + + long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] @@ -421,7 +489,7 @@ Returns an array with the IDs of the points that form the connection with the gi .. rst-class:: classref-method -:ref:`int` **get_point_count**\ (\ ) |const| +:ref:`int` **get_point_count**\ (\ ) |const| :ref:`🔗` Returns the number of points currently in the points pool. @@ -433,7 +501,7 @@ Returns the number of points currently in the points pool. .. rst-class:: classref-method -:ref:`PackedInt64Array` **get_point_ids**\ (\ ) +:ref:`PackedInt64Array` **get_point_ids**\ (\ ) :ref:`🔗` Returns an array of all point IDs. @@ -445,11 +513,15 @@ Returns an array of all point IDs. .. rst-class:: classref-method -:ref:`PackedVector3Array` **get_point_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) +:ref:`PackedVector3Array` **get_point_path**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the points that are in the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path. -\ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty :ref:`PackedVector3Array` and will print an error message. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty array and will print an error message. + +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. .. rst-class:: classref-item-separator @@ -459,7 +531,7 @@ Returns an array with the points that are in the path found by AStar3D between t .. rst-class:: classref-method -:ref:`Vector3` **get_point_position**\ (\ id\: :ref:`int`\ ) |const| +:ref:`Vector3` **get_point_position**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the position of the point associated with the given ``id``. @@ -471,7 +543,7 @@ Returns the position of the point associated with the given ``id``. .. rst-class:: classref-method -:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`int`\ ) |const| +:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the weight scale of the point associated with the given ``id``. @@ -483,7 +555,7 @@ Returns the weight scale of the point associated with the given ``id``. .. rst-class:: classref-method -:ref:`bool` **has_point**\ (\ id\: :ref:`int`\ ) |const| +:ref:`bool` **has_point**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether a point associated with the given ``id`` exists. @@ -495,7 +567,7 @@ Returns whether a point associated with the given ``id`` exists. .. rst-class:: classref-method -:ref:`bool` **is_point_disabled**\ (\ id\: :ref:`int`\ ) |const| +:ref:`bool` **is_point_disabled**\ (\ id\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. @@ -507,7 +579,7 @@ Returns whether a point is disabled or not for pathfinding. By default, all poin .. rst-class:: classref-method -|void| **remove_point**\ (\ id\: :ref:`int`\ ) +|void| **remove_point**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Removes the point associated with the given ``id`` from the points pool. @@ -519,9 +591,9 @@ Removes the point associated with the given ``id`` from the points pool. .. rst-class:: classref-method -|void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) +|void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) :ref:`🔗` -Reserves space internally for ``num_nodes`` points. Useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity. +Reserves space internally for ``num_nodes`` points. Useful if you're adding a known large number of points at once, such as points on a grid. .. rst-class:: classref-item-separator @@ -531,7 +603,7 @@ Reserves space internally for ``num_nodes`` points. Useful if you're adding a kn .. rst-class:: classref-method -|void| **set_point_disabled**\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) +|void| **set_point_disabled**\ (\ id\: :ref:`int`, disabled\: :ref:`bool` = true\ ) :ref:`🔗` Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. @@ -543,7 +615,7 @@ Disables or enables the specified point for pathfinding. Useful for making a tem .. rst-class:: classref-method -|void| **set_point_position**\ (\ id\: :ref:`int`, position\: :ref:`Vector3`\ ) +|void| **set_point_position**\ (\ id\: :ref:`int`, position\: :ref:`Vector3`\ ) :ref:`🔗` Sets the ``position`` for the point with the given ``id``. @@ -555,11 +627,12 @@ Sets the ``position`` for the point with the given ``id``. .. rst-class:: classref-method -|void| **set_point_weight_scale**\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) +|void| **set_point_weight_scale**\ (\ id\: :ref:`int`, weight_scale\: :ref:`float`\ ) :ref:`🔗` -Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost` when determining the overall cost of traveling across a segment from a neighboring point to this point. +Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_astargrid2d.rst b/classes/class_astargrid2d.rst index 5b9a394fbd6..8faf51d3ca6 100644 --- a/classes/class_astargrid2d.rst +++ b/classes/class_astargrid2d.rst @@ -21,7 +21,7 @@ Description **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. -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: +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:: @@ -32,8 +32,8 @@ To use **AStarGrid2D**, you only need to 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-introduction-group + +Tutorials +--------- + +- `Grid-based Navigation with AStarGrid2D Demo `__ .. rst-class:: classref-reftable-group @@ -84,39 +91,41 @@ Methods .. table:: :widths: auto - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear`\ (\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`fill_solid_region`\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`fill_weight_scale_region`\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Vector2i`\] | :ref:`get_id_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_dirty`\ (\ ) |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_in_bounds`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_in_boundsv`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_point_solid`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_point_solid`\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`update`\ (\ ) | - +--------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`Vector2i`, end_id\: :ref:`Vector2i`\ ) |virtual| |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill_solid_region`\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill_weight_scale_region`\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Vector2i`\] | :ref:`get_id_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`get_point_data_in_region`\ (\ region\: :ref:`Rect2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_dirty`\ (\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_in_bounds`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_in_boundsv`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_point_solid`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_solid`\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update`\ (\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -131,7 +140,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **Heuristic**: +enum **Heuristic**: :ref:`🔗` .. _class_AStarGrid2D_constant_HEURISTIC_EUCLIDEAN: @@ -210,7 +219,7 @@ Represents the size of the :ref:`Heuristic` enum. .. rst-class:: classref-enumeration -enum **DiagonalMode**: +enum **DiagonalMode**: :ref:`🔗` .. _class_AStarGrid2D_constant_DIAGONAL_MODE_ALWAYS: @@ -260,7 +269,7 @@ Represents the size of the :ref:`DiagonalMode` en .. rst-class:: classref-enumeration -enum **CellShape**: +enum **CellShape**: :ref:`🔗` .. _class_AStarGrid2D_constant_CELL_SHAPE_SQUARE: @@ -307,14 +316,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`CellShape` **cell_shape** = ``0`` +:ref:`CellShape` **cell_shape** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_cell_shape**\ (\ value\: :ref:`CellShape`\ ) - :ref:`CellShape` **get_cell_shape**\ (\ ) -The cell shape. Affects how the positions are placed in the grid. If changed, :ref:`update` needs to be called before finding the next path. +The cell shape. Affects how the positions are placed in the grid. If changed, :ref:`update()` needs to be called before finding the next path. .. rst-class:: classref-item-separator @@ -324,14 +333,14 @@ The cell shape. Affects how the positions are placed in the grid. If changed, :r .. rst-class:: classref-property -:ref:`Vector2` **cell_size** = ``Vector2(1, 1)`` +:ref:`Vector2` **cell_size** = ``Vector2(1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_cell_size**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_cell_size**\ (\ ) -The size of the point cell which will be applied to calculate the resulting point position returned by :ref:`get_point_path`. If changed, :ref:`update` needs to be called before finding the next path. +The size of the point cell which will be applied to calculate the resulting point position returned by :ref:`get_point_path()`. If changed, :ref:`update()` needs to be called before finding the next path. .. rst-class:: classref-item-separator @@ -341,14 +350,14 @@ The size of the point cell which will be applied to calculate the resulting poin .. rst-class:: classref-property -:ref:`Heuristic` **default_compute_heuristic** = ``0`` +:ref:`Heuristic` **default_compute_heuristic** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_default_compute_heuristic**\ (\ value\: :ref:`Heuristic`\ ) - :ref:`Heuristic` **get_default_compute_heuristic**\ (\ ) -The default :ref:`Heuristic` which will be used to calculate the cost between two points if :ref:`_compute_cost` was not overridden. +The default :ref:`Heuristic` which will be used to calculate the cost between two points if :ref:`_compute_cost()` was not overridden. .. rst-class:: classref-item-separator @@ -358,14 +367,14 @@ The default :ref:`Heuristic` which will be used to c .. rst-class:: classref-property -:ref:`Heuristic` **default_estimate_heuristic** = ``0`` +:ref:`Heuristic` **default_estimate_heuristic** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_default_estimate_heuristic**\ (\ value\: :ref:`Heuristic`\ ) - :ref:`Heuristic` **get_default_estimate_heuristic**\ (\ ) -The default :ref:`Heuristic` which will be used to calculate the cost between the point and the end point if :ref:`_estimate_cost` was not overridden. +The default :ref:`Heuristic` which will be used to calculate the cost between the point and the end point if :ref:`_estimate_cost()` was not overridden. .. rst-class:: classref-item-separator @@ -375,7 +384,7 @@ The default :ref:`Heuristic` which will be used to c .. rst-class:: classref-property -:ref:`DiagonalMode` **diagonal_mode** = ``0`` +:ref:`DiagonalMode` **diagonal_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -392,7 +401,7 @@ A specific :ref:`DiagonalMode` mode which will fo .. rst-class:: classref-property -:ref:`bool` **jumping_enabled** = ``false`` +:ref:`bool` **jumping_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -411,14 +420,14 @@ Enables or disables jumping to skip up the intermediate points and speeds up the .. rst-class:: classref-property -:ref:`Vector2` **offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_offset**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_offset**\ (\ ) -The offset of the grid which will be applied to calculate the resulting point position returned by :ref:`get_point_path`. If changed, :ref:`update` needs to be called before finding the next path. +The offset of the grid which will be applied to calculate the resulting point position returned by :ref:`get_point_path()`. If changed, :ref:`update()` needs to be called before finding the next path. .. rst-class:: classref-item-separator @@ -428,14 +437,14 @@ The offset of the grid which will be applied to calculate the resulting point po .. rst-class:: classref-property -:ref:`Rect2i` **region** = ``Rect2i(0, 0, 0, 0)`` +:ref:`Rect2i` **region** = ``Rect2i(0, 0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_region**\ (\ value\: :ref:`Rect2i`\ ) - :ref:`Rect2i` **get_region**\ (\ ) -The region of grid cells available for pathfinding. If changed, :ref:`update` needs to be called before finding the next path. +The region of grid cells available for pathfinding. If changed, :ref:`update()` needs to be called before finding the next path. .. rst-class:: classref-item-separator @@ -445,7 +454,7 @@ The region of grid cells available for pathfinding. If changed, :ref:`update` **size** = ``Vector2i(0, 0)`` +:ref:`Vector2i` **size** = ``Vector2i(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -454,7 +463,7 @@ The region of grid cells available for pathfinding. If changed, :ref:`update` instead. -The size of the grid (number of cells of size :ref:`cell_size` on each axis). If changed, :ref:`update` needs to be called before finding the next path. +The size of the grid (number of cells of size :ref:`cell_size` on each axis). If changed, :ref:`update()` needs to be called before finding the next path. .. rst-class:: classref-section-separator @@ -469,7 +478,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| +:ref:`float` **_compute_cost**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| :ref:`🔗` Called when computing the cost between two connected points. @@ -483,7 +492,7 @@ Note that this function is hidden in the default **AStarGrid2D** class. .. rst-class:: classref-method -:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`Vector2i`, end_id\: :ref:`Vector2i`\ ) |virtual| |const| :ref:`🔗` Called when estimating the cost between a point and the path's ending point. @@ -497,7 +506,7 @@ Note that this function is hidden in the default **AStarGrid2D** class. .. rst-class:: classref-method -|void| **clear**\ (\ ) +|void| **clear**\ (\ ) :ref:`🔗` Clears the grid and sets the :ref:`region` to ``Rect2i(0, 0, 0, 0)``. @@ -509,11 +518,11 @@ Clears the grid and sets the :ref:`region` to .. rst-class:: classref-method -|void| **fill_solid_region**\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) +|void| **fill_solid_region**\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) :ref:`🔗` Fills the given ``region`` on the grid with the specified value for the solid flag. -\ **Note:** Calling :ref:`update` is not needed after the call of this function. +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. .. rst-class:: classref-item-separator @@ -523,11 +532,11 @@ Fills the given ``region`` on the grid with the specified value for the solid fl .. rst-class:: classref-method -|void| **fill_weight_scale_region**\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) +|void| **fill_weight_scale_region**\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) :ref:`🔗` Fills the given ``region`` on the grid with the specified value for the weight scale. -\ **Note:** Calling :ref:`update` is not needed after the call of this function. +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. .. rst-class:: classref-item-separator @@ -537,10 +546,26 @@ Fills the given ``region`` on the grid with the specified value for the weight s .. rst-class:: classref-method -:ref:`Array`\[:ref:`Vector2i`\] **get_id_path**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) +:ref:`Array`\[:ref:`Vector2i`\] **get_id_path**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is solid the search may take an unusually long time to finish. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_point_data_in_region: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **get_point_data_in_region**\ (\ region\: :ref:`Rect2i`\ ) |const| :ref:`🔗` + +Returns an array of dictionaries with point data (``id``: :ref:`Vector2i`, ``position``: :ref:`Vector2`, ``solid``: :ref:`bool`, ``weight_scale``: :ref:`float`) within a ``region``. + .. rst-class:: classref-item-separator ---- @@ -549,11 +574,15 @@ Returns an array with the IDs of the points that form the path found by AStar2D .. rst-class:: classref-method -:ref:`PackedVector2Array` **get_point_path**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) +:ref:`PackedVector2Array` **get_point_path**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) :ref:`🔗` Returns an array with the points that are in the path found by **AStarGrid2D** between the given points. The array is ordered from the starting point to the ending point of the path. -\ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty :ref:`PackedVector3Array` and will print an error message. +If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty array and will print an error message. + +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is solid the search may take an unusually long time to finish. .. rst-class:: classref-item-separator @@ -563,7 +592,7 @@ Returns an array with the points that are in the path found by **AStarGrid2D** b .. rst-class:: classref-method -:ref:`Vector2` **get_point_position**\ (\ id\: :ref:`Vector2i`\ ) |const| +:ref:`Vector2` **get_point_position**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns the position of the point associated with the given ``id``. @@ -575,7 +604,7 @@ Returns the position of the point associated with the given ``id``. .. rst-class:: classref-method -:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`Vector2i`\ ) |const| +:ref:`float` **get_point_weight_scale**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns the weight scale of the point associated with the given ``id``. @@ -587,9 +616,9 @@ Returns the weight scale of the point associated with the given ``id``. .. rst-class:: classref-method -:ref:`bool` **is_dirty**\ (\ ) |const| +:ref:`bool` **is_dirty**\ (\ ) |const| :ref:`🔗` -Indicates that the grid parameters were changed and :ref:`update` needs to be called. +Indicates that the grid parameters were changed and :ref:`update()` needs to be called. .. rst-class:: classref-item-separator @@ -599,7 +628,7 @@ Indicates that the grid parameters were changed and :ref:`update` **is_in_bounds**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| +:ref:`bool` **is_in_bounds**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if the ``x`` and ``y`` is a valid grid coordinate (id), i.e. if it is inside :ref:`region`. Equivalent to ``region.has_point(Vector2i(x, y))``. @@ -611,7 +640,7 @@ Returns ``true`` if the ``x`` and ``y`` is a valid grid coordinate (id), i.e. if .. rst-class:: classref-method -:ref:`bool` **is_in_boundsv**\ (\ id\: :ref:`Vector2i`\ ) |const| +:ref:`bool` **is_in_boundsv**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns ``true`` if the ``id`` vector is a valid grid coordinate, i.e. if it is inside :ref:`region`. Equivalent to ``region.has_point(id)``. @@ -623,7 +652,7 @@ Returns ``true`` if the ``id`` vector is a valid grid coordinate, i.e. if it is .. rst-class:: classref-method -:ref:`bool` **is_point_solid**\ (\ id\: :ref:`Vector2i`\ ) |const| +:ref:`bool` **is_point_solid**\ (\ id\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns ``true`` if a point is disabled for pathfinding. By default, all points are enabled. @@ -635,11 +664,11 @@ Returns ``true`` if a point is disabled for pathfinding. By default, all points .. rst-class:: classref-method -|void| **set_point_solid**\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) +|void| **set_point_solid**\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) :ref:`🔗` Disables or enables the specified point for pathfinding. Useful for making an obstacle. By default, all points are enabled. -\ **Note:** Calling :ref:`update` is not needed after the call of this function. +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. .. rst-class:: classref-item-separator @@ -649,11 +678,11 @@ Disables or enables the specified point for pathfinding. Useful for making an ob .. rst-class:: classref-method -|void| **set_point_weight_scale**\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) +|void| **set_point_weight_scale**\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) :ref:`🔗` -Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost` when determining the overall cost of traveling across a segment from a neighboring point to this point. +Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scale`` is multiplied by the result of :ref:`_compute_cost()` when determining the overall cost of traveling across a segment from a neighboring point to this point. -\ **Note:** Calling :ref:`update` is not needed after the call of this function. +\ **Note:** Calling :ref:`update()` is not needed after the call of this function. .. rst-class:: classref-item-separator @@ -663,13 +692,14 @@ Sets the ``weight_scale`` for the point with the given ``id``. The ``weight_scal .. rst-class:: classref-method -|void| **update**\ (\ ) +|void| **update**\ (\ ) :ref:`🔗` -Updates the internal state of the grid according to the parameters to prepare it to search the path. Needs to be called if parameters like :ref:`region`, :ref:`cell_size` or :ref:`offset` are changed. :ref:`is_dirty` will return ``true`` if this is the case and this needs to be called. +Updates the internal state of the grid according to the parameters to prepare it to search the path. Needs to be called if parameters like :ref:`region`, :ref:`cell_size` or :ref:`offset` are changed. :ref:`is_dirty()` will return ``true`` if this is the case and this needs to be called. \ **Note:** All point data (solidity and weight scale) will be cleared. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_atlastexture.rst b/classes/class_atlastexture.rst index dfa08025df5..9dc025ebfd0 100644 --- a/classes/class_atlastexture.rst +++ b/classes/class_atlastexture.rst @@ -23,7 +23,7 @@ Description Multiple **AtlasTexture** resources can be cropped from the same :ref:`atlas`. Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls. -\ **Note:** **AtlasTexture** cannot be used in an :ref:`AnimatedTexture`, and may not tile properly in nodes such as :ref:`TextureRect`, when inside other **AtlasTexture** resources. +\ **Note:** **AtlasTexture** cannot be used in an :ref:`AnimatedTexture`, and will not tile properly in nodes such as :ref:`TextureRect` or :ref:`Sprite2D`. To tile an **AtlasTexture**, modify its :ref:`region` instead. .. rst-class:: classref-reftable-group @@ -58,7 +58,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Texture2D` **atlas** +:ref:`Texture2D` **atlas** :ref:`🔗` .. rst-class:: classref-property-setget @@ -75,7 +75,7 @@ The texture that contains the atlas. Can be any type inheriting from :ref:`Textu .. rst-class:: classref-property -:ref:`bool` **filter_clip** = ``false`` +:ref:`bool` **filter_clip** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -92,7 +92,7 @@ If ``true``, the area outside of the :ref:`region` **margin** = ``Rect2(0, 0, 0, 0)`` +:ref:`Rect2` **margin** = ``Rect2(0, 0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -109,16 +109,17 @@ The margin around the :ref:`region`. Useful .. rst-class:: classref-property -:ref:`Rect2` **region** = ``Rect2(0, 0, 0, 0)`` +:ref:`Rect2` **region** = ``Rect2(0, 0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_region**\ (\ value\: :ref:`Rect2`\ ) - :ref:`Rect2` **get_region**\ (\ ) -The region used to draw the :ref:`atlas`. +The region used to draw the :ref:`atlas`. If either dimension of the region's size is ``0``, the value from :ref:`atlas` size will be used for that axis instead. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiobuslayout.rst b/classes/class_audiobuslayout.rst index 80fe120f299..9ad3ccbf1f5 100644 --- a/classes/class_audiobuslayout.rst +++ b/classes/class_audiobuslayout.rst @@ -22,6 +22,7 @@ Description Stores position, muting, solo, bypass, effects, effect position, volume, and the connections between buses. See :ref:`AudioServer` for usage. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffect.rst b/classes/class_audioeffect.rst index 5644677a810..fc5631d5312 100644 --- a/classes/class_audioeffect.rst +++ b/classes/class_audioeffect.rst @@ -12,7 +12,7 @@ AudioEffect **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioEffectAmplify`, :ref:`AudioEffectCapture`, :ref:`AudioEffectChorus`, :ref:`AudioEffectCompressor`, :ref:`AudioEffectDelay`, :ref:`AudioEffectDistortion`, :ref:`AudioEffectEQ`, :ref:`AudioEffectFilter`, :ref:`AudioEffectLimiter`, :ref:`AudioEffectPanner`, :ref:`AudioEffectPhaser`, :ref:`AudioEffectPitchShift`, :ref:`AudioEffectRecord`, :ref:`AudioEffectReverb`, :ref:`AudioEffectSpectrumAnalyzer`, :ref:`AudioEffectStereoEnhance` +**Inherited By:** :ref:`AudioEffectAmplify`, :ref:`AudioEffectCapture`, :ref:`AudioEffectChorus`, :ref:`AudioEffectCompressor`, :ref:`AudioEffectDelay`, :ref:`AudioEffectDistortion`, :ref:`AudioEffectEQ`, :ref:`AudioEffectFilter`, :ref:`AudioEffectHardLimiter`, :ref:`AudioEffectLimiter`, :ref:`AudioEffectPanner`, :ref:`AudioEffectPhaser`, :ref:`AudioEffectPitchShift`, :ref:`AudioEffectRecord`, :ref:`AudioEffectReverb`, :ref:`AudioEffectSpectrumAnalyzer`, :ref:`AudioEffectStereoEnhance` Base class for audio effect resources. @@ -21,7 +21,7 @@ Base class for audio effect resources. Description ----------- -The base :ref:`Resource` for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through :ref:`AudioServer.add_bus_effect`, :ref:`AudioServer.remove_bus_effect`, and :ref:`AudioServer.get_bus_effect`. +The base :ref:`Resource` for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through :ref:`AudioServer.add_bus_effect()`, :ref:`AudioServer.remove_bus_effect()`, and :ref:`AudioServer.get_bus_effect()`. When applied on a bus, an audio effect creates a corresponding :ref:`AudioEffectInstance`. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties. @@ -32,7 +32,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` -- `Audio Mic Record Demo `__ +- `Audio Microphone Record Demo `__ .. rst-class:: classref-reftable-group @@ -42,9 +42,9 @@ Methods .. table:: :widths: auto - +-------------------------------------------------------+------------------------------------------------------------------------------------+ - | :ref:`AudioEffectInstance` | :ref:`_instantiate`\ (\ ) |virtual| | - +-------------------------------------------------------+------------------------------------------------------------------------------------+ + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------+ + | :ref:`AudioEffectInstance` | :ref:`_instantiate`\ (\ ) |virtual| |required| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -59,25 +59,26 @@ Method Descriptions .. rst-class:: classref-method -:ref:`AudioEffectInstance` **_instantiate**\ (\ ) |virtual| +:ref:`AudioEffectInstance` **_instantiate**\ (\ ) |virtual| |required| :ref:`🔗` -Override this method to customize the :ref:`AudioEffectInstance` created when this effect is applied on a bus in the editor's Audio panel, or through :ref:`AudioServer.add_bus_effect`. +Override this method to customize the :ref:`AudioEffectInstance` created when this effect is applied on a bus in the editor's Audio panel, or through :ref:`AudioServer.add_bus_effect()`. :: extends AudioEffect - + @export var strength = 4.0 - + func _instantiate(): var effect = CustomAudioEffectInstance.new() effect.base = self - + return effect \ **Note:** It is recommended to keep a reference to the original **AudioEffect** in the new instance. Depending on the implementation this allows the effect instance to listen for changes at run-time and be modified accordingly. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectamplify.rst b/classes/class_audioeffectamplify.rst index 4b3aeea0bf6..764c65e237d 100644 --- a/classes/class_audioeffectamplify.rst +++ b/classes/class_audioeffectamplify.rst @@ -36,9 +36,11 @@ Properties .. table:: :widths: auto - +---------------------------+---------------------------------------------------------------+---------+ - | :ref:`float` | :ref:`volume_db` | ``0.0`` | - +---------------------------+---------------------------------------------------------------+---------+ + +---------------------------+-----------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`volume_db` | ``0.0`` | + +---------------------------+-----------------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`volume_linear` | | + +---------------------------+-----------------------------------------------------------------------+---------+ .. rst-class:: classref-section-separator @@ -53,7 +55,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **volume_db** = ``0.0`` +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -62,7 +64,27 @@ Property Descriptions Amount of amplification in decibels. Positive values make the sound louder, negative values make it quieter. Value can range from -80 to 24. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectAmplify_property_volume_linear: + +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +Amount of amplification as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectbandlimitfilter.rst b/classes/class_audioeffectbandlimitfilter.rst index 031ef97508c..1fdfe575356 100644 --- a/classes/class_audioeffectbandlimitfilter.rst +++ b/classes/class_audioeffectbandlimitfilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectbandpassfilter.rst b/classes/class_audioeffectbandpassfilter.rst index 186024ed7ae..1647ea0cdc9 100644 --- a/classes/class_audioeffectbandpassfilter.rst +++ b/classes/class_audioeffectbandpassfilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectcapture.rst b/classes/class_audioeffectcapture.rst index 75d76d9f05b..e4ce9269afb 100644 --- a/classes/class_audioeffectcapture.rst +++ b/classes/class_audioeffectcapture.rst @@ -21,7 +21,7 @@ Description AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer. -Application code should consume these audio frames from this ring buffer using :ref:`get_buffer` and process it as needed, for example to capture data from an :ref:`AudioStreamMicrophone`, implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating-point PCM. +Application code should consume these audio frames from this ring buffer using :ref:`get_buffer()` and process it as needed, for example to capture data from an :ref:`AudioStreamMicrophone`, implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating-point PCM. Unlike :ref:`AudioEffectRecord`, this effect only returns the raw audio samples instead of encoding them into an :ref:`AudioStream`. @@ -81,7 +81,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **buffer_length** = ``0.1`` +:ref:`float` **buffer_length** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -103,7 +103,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`bool` **can_get_buffer**\ (\ frames\: :ref:`int`\ ) |const| +:ref:`bool` **can_get_buffer**\ (\ frames\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if at least ``frames`` audio frames are available to read in the internal ring buffer. @@ -115,7 +115,7 @@ Returns ``true`` if at least ``frames`` audio frames are available to read in th .. rst-class:: classref-method -|void| **clear_buffer**\ (\ ) +|void| **clear_buffer**\ (\ ) :ref:`🔗` Clears the internal ring buffer. @@ -129,7 +129,7 @@ Clears the internal ring buffer. .. rst-class:: classref-method -:ref:`PackedVector2Array` **get_buffer**\ (\ frames\: :ref:`int`\ ) +:ref:`PackedVector2Array` **get_buffer**\ (\ frames\: :ref:`int`\ ) :ref:`🔗` Gets the next ``frames`` audio samples from the internal ring buffer. @@ -145,7 +145,7 @@ The samples are signed floating-point PCM between ``-1`` and ``1``. You will hav .. rst-class:: classref-method -:ref:`int` **get_buffer_length_frames**\ (\ ) |const| +:ref:`int` **get_buffer_length_frames**\ (\ ) |const| :ref:`🔗` Returns the total size of the internal ring buffer in frames. @@ -157,7 +157,7 @@ Returns the total size of the internal ring buffer in frames. .. rst-class:: classref-method -:ref:`int` **get_discarded_frames**\ (\ ) |const| +:ref:`int` **get_discarded_frames**\ (\ ) |const| :ref:`🔗` Returns the number of audio frames discarded from the audio bus due to full buffer. @@ -169,9 +169,9 @@ Returns the number of audio frames discarded from the audio bus due to full buff .. rst-class:: classref-method -:ref:`int` **get_frames_available**\ (\ ) |const| +:ref:`int` **get_frames_available**\ (\ ) |const| :ref:`🔗` -Returns the number of frames available to read using :ref:`get_buffer`. +Returns the number of frames available to read using :ref:`get_buffer()`. .. rst-class:: classref-item-separator @@ -181,11 +181,12 @@ Returns the number of frames available to read using :ref:`get_buffer` **get_pushed_frames**\ (\ ) |const| +:ref:`int` **get_pushed_frames**\ (\ ) |const| :ref:`🔗` Returns the number of audio frames inserted from the audio bus. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectchorus.rst b/classes/class_audioeffectchorus.rst index 02efed89f78..db80798e7fe 100644 --- a/classes/class_audioeffectchorus.rst +++ b/classes/class_audioeffectchorus.rst @@ -139,7 +139,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **dry** = ``1.0`` +:ref:`float` **dry** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -156,7 +156,7 @@ The effect's raw signal. .. rst-class:: classref-property -:ref:`float` **voice/1/cutoff_hz** = ``8000.0`` +:ref:`float` **voice/1/cutoff_hz** = ``8000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -173,7 +173,7 @@ The voice's cutoff frequency. .. rst-class:: classref-property -:ref:`float` **voice/1/delay_ms** = ``15.0`` +:ref:`float` **voice/1/delay_ms** = ``15.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -190,7 +190,7 @@ The voice's signal delay. .. rst-class:: classref-property -:ref:`float` **voice/1/depth_ms** = ``2.0`` +:ref:`float` **voice/1/depth_ms** = ``2.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -207,7 +207,7 @@ The voice filter's depth. .. rst-class:: classref-property -:ref:`float` **voice/1/level_db** = ``0.0`` +:ref:`float` **voice/1/level_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -224,7 +224,7 @@ The voice's volume. .. rst-class:: classref-property -:ref:`float` **voice/1/pan** = ``-0.5`` +:ref:`float` **voice/1/pan** = ``-0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -241,7 +241,7 @@ The voice's pan level. .. rst-class:: classref-property -:ref:`float` **voice/1/rate_hz** = ``0.8`` +:ref:`float` **voice/1/rate_hz** = ``0.8`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -258,7 +258,7 @@ The voice's filter rate. .. rst-class:: classref-property -:ref:`float` **voice/2/cutoff_hz** = ``8000.0`` +:ref:`float` **voice/2/cutoff_hz** = ``8000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -275,7 +275,7 @@ The voice's cutoff frequency. .. rst-class:: classref-property -:ref:`float` **voice/2/delay_ms** = ``20.0`` +:ref:`float` **voice/2/delay_ms** = ``20.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -292,7 +292,7 @@ The voice's signal delay. .. rst-class:: classref-property -:ref:`float` **voice/2/depth_ms** = ``3.0`` +:ref:`float` **voice/2/depth_ms** = ``3.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -309,7 +309,7 @@ The voice filter's depth. .. rst-class:: classref-property -:ref:`float` **voice/2/level_db** = ``0.0`` +:ref:`float` **voice/2/level_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -326,7 +326,7 @@ The voice's volume. .. rst-class:: classref-property -:ref:`float` **voice/2/pan** = ``0.5`` +:ref:`float` **voice/2/pan** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -343,7 +343,7 @@ The voice's pan level. .. rst-class:: classref-property -:ref:`float` **voice/2/rate_hz** = ``1.2`` +:ref:`float` **voice/2/rate_hz** = ``1.2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -360,7 +360,7 @@ The voice's filter rate. .. rst-class:: classref-property -:ref:`float` **voice/3/cutoff_hz** +:ref:`float` **voice/3/cutoff_hz** :ref:`🔗` .. rst-class:: classref-property-setget @@ -377,7 +377,7 @@ The voice's cutoff frequency. .. rst-class:: classref-property -:ref:`float` **voice/3/delay_ms** +:ref:`float` **voice/3/delay_ms** :ref:`🔗` .. rst-class:: classref-property-setget @@ -394,7 +394,7 @@ The voice's signal delay. .. rst-class:: classref-property -:ref:`float` **voice/3/depth_ms** +:ref:`float` **voice/3/depth_ms** :ref:`🔗` .. rst-class:: classref-property-setget @@ -411,7 +411,7 @@ The voice filter's depth. .. rst-class:: classref-property -:ref:`float` **voice/3/level_db** +:ref:`float` **voice/3/level_db** :ref:`🔗` .. rst-class:: classref-property-setget @@ -428,7 +428,7 @@ The voice's volume. .. rst-class:: classref-property -:ref:`float` **voice/3/pan** +:ref:`float` **voice/3/pan** :ref:`🔗` .. rst-class:: classref-property-setget @@ -445,7 +445,7 @@ The voice's pan level. .. rst-class:: classref-property -:ref:`float` **voice/3/rate_hz** +:ref:`float` **voice/3/rate_hz** :ref:`🔗` .. rst-class:: classref-property-setget @@ -462,7 +462,7 @@ The voice's filter rate. .. rst-class:: classref-property -:ref:`float` **voice/4/cutoff_hz** +:ref:`float` **voice/4/cutoff_hz** :ref:`🔗` .. rst-class:: classref-property-setget @@ -479,7 +479,7 @@ The voice's cutoff frequency. .. rst-class:: classref-property -:ref:`float` **voice/4/delay_ms** +:ref:`float` **voice/4/delay_ms** :ref:`🔗` .. rst-class:: classref-property-setget @@ -496,7 +496,7 @@ The voice's signal delay. .. rst-class:: classref-property -:ref:`float` **voice/4/depth_ms** +:ref:`float` **voice/4/depth_ms** :ref:`🔗` .. rst-class:: classref-property-setget @@ -513,7 +513,7 @@ The voice filter's depth. .. rst-class:: classref-property -:ref:`float` **voice/4/level_db** +:ref:`float` **voice/4/level_db** :ref:`🔗` .. rst-class:: classref-property-setget @@ -530,7 +530,7 @@ The voice's volume. .. rst-class:: classref-property -:ref:`float` **voice/4/pan** +:ref:`float` **voice/4/pan** :ref:`🔗` .. rst-class:: classref-property-setget @@ -547,7 +547,7 @@ The voice's pan level. .. rst-class:: classref-property -:ref:`float` **voice/4/rate_hz** +:ref:`float` **voice/4/rate_hz** :ref:`🔗` .. rst-class:: classref-property-setget @@ -564,7 +564,7 @@ The voice's filter rate. .. rst-class:: classref-property -:ref:`int` **voice_count** = ``2`` +:ref:`int` **voice_count** = ``2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -581,7 +581,7 @@ The number of voices in the effect. .. rst-class:: classref-property -:ref:`float` **wet** = ``0.5`` +:ref:`float` **wet** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -603,7 +603,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` .. container:: contribute @@ -617,7 +617,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_voice_delay_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` .. container:: contribute @@ -631,7 +631,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_voice_depth_ms**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` .. container:: contribute @@ -645,7 +645,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_voice_level_db**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` .. container:: contribute @@ -659,7 +659,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_voice_pan**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` .. container:: contribute @@ -673,7 +673,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_voice_rate_hz**\ (\ voice_idx\: :ref:`int`\ ) |const| :ref:`🔗` .. container:: contribute @@ -687,7 +687,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) +|void| **set_voice_cutoff_hz**\ (\ voice_idx\: :ref:`int`, cutoff_hz\: :ref:`float`\ ) :ref:`🔗` .. container:: contribute @@ -701,7 +701,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) +|void| **set_voice_delay_ms**\ (\ voice_idx\: :ref:`int`, delay_ms\: :ref:`float`\ ) :ref:`🔗` .. container:: contribute @@ -715,7 +715,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) +|void| **set_voice_depth_ms**\ (\ voice_idx\: :ref:`int`, depth_ms\: :ref:`float`\ ) :ref:`🔗` .. container:: contribute @@ -729,7 +729,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) +|void| **set_voice_level_db**\ (\ voice_idx\: :ref:`int`, level_db\: :ref:`float`\ ) :ref:`🔗` .. container:: contribute @@ -743,7 +743,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) +|void| **set_voice_pan**\ (\ voice_idx\: :ref:`int`, pan\: :ref:`float`\ ) :ref:`🔗` .. container:: contribute @@ -757,13 +757,14 @@ Method Descriptions .. rst-class:: classref-method -|void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) +|void| **set_voice_rate_hz**\ (\ voice_idx\: :ref:`int`, rate_hz\: :ref:`float`\ ) :ref:`🔗` .. container:: contribute There is currently no description for this method. Please help us by :ref:`contributing one `! .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectcompressor.rst b/classes/class_audioeffectcompressor.rst index b19b05bd427..77abbe9c665 100644 --- a/classes/class_audioeffectcompressor.rst +++ b/classes/class_audioeffectcompressor.rst @@ -25,7 +25,7 @@ Dynamic range compressor reduces the level of the sound when the amplitude goes Compressor has many uses in the mix: -- In the Master bus to compress the whole output (although an :ref:`AudioEffectLimiter` is probably better). +- In the Master bus to compress the whole output (although an :ref:`AudioEffectHardLimiter` is probably better). - In voice channels to ensure they sound as balanced as possible. @@ -77,7 +77,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **attack_us** = ``20.0`` +:ref:`float` **attack_us** = ``20.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -94,7 +94,7 @@ Compressor's reaction time when the signal exceeds the threshold, in microsecond .. rst-class:: classref-property -:ref:`float` **gain** = ``0.0`` +:ref:`float` **gain** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -111,7 +111,7 @@ Gain applied to the output signal. .. rst-class:: classref-property -:ref:`float` **mix** = ``1.0`` +:ref:`float` **mix** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -128,7 +128,7 @@ Balance between original signal and effect signal. Value can range from 0 (total .. rst-class:: classref-property -:ref:`float` **ratio** = ``4.0`` +:ref:`float` **ratio** = ``4.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -145,7 +145,7 @@ Amount of compression applied to the audio once it passes the threshold level. T .. rst-class:: classref-property -:ref:`float` **release_ms** = ``250.0`` +:ref:`float` **release_ms** = ``250.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -162,7 +162,7 @@ Compressor's delay time to stop reducing the signal after the signal level falls .. rst-class:: classref-property -:ref:`StringName` **sidechain** = ``&""`` +:ref:`StringName` **sidechain** = ``&""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -179,7 +179,7 @@ Reduce the sound level using another audio bus for threshold detection. .. rst-class:: classref-property -:ref:`float` **threshold** = ``0.0`` +:ref:`float` **threshold** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -189,6 +189,7 @@ Reduce the sound level using another audio bus for threshold detection. The level above which compression is applied to the audio. Value can range from -60 to 0. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectdelay.rst b/classes/class_audioeffectdelay.rst index 0d1d8cbfcdc..3bdebd7b4a1 100644 --- a/classes/class_audioeffectdelay.rst +++ b/classes/class_audioeffectdelay.rst @@ -79,7 +79,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **dry** = ``1.0`` +:ref:`float` **dry** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -96,7 +96,7 @@ Output percent of original sound. At 0, only delayed sounds are output. Value ca .. rst-class:: classref-property -:ref:`bool` **feedback_active** = ``false`` +:ref:`bool` **feedback_active** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -113,7 +113,7 @@ If ``true``, feedback is enabled. .. rst-class:: classref-property -:ref:`float` **feedback_delay_ms** = ``340.0`` +:ref:`float` **feedback_delay_ms** = ``340.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -130,7 +130,7 @@ Feedback delay time in milliseconds. .. rst-class:: classref-property -:ref:`float` **feedback_level_db** = ``-6.0`` +:ref:`float` **feedback_level_db** = ``-6.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -147,7 +147,7 @@ Sound level for feedback. .. rst-class:: classref-property -:ref:`float` **feedback_lowpass** = ``16000.0`` +:ref:`float` **feedback_lowpass** = ``16000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -164,7 +164,7 @@ Low-pass filter for feedback, in Hz. Frequencies below this value are filtered o .. rst-class:: classref-property -:ref:`bool` **tap1_active** = ``true`` +:ref:`bool` **tap1_active** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -181,7 +181,7 @@ If ``true``, the first tap will be enabled. .. rst-class:: classref-property -:ref:`float` **tap1_delay_ms** = ``250.0`` +:ref:`float` **tap1_delay_ms** = ``250.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,7 +198,7 @@ First tap delay time in milliseconds. .. rst-class:: classref-property -:ref:`float` **tap1_level_db** = ``-6.0`` +:ref:`float` **tap1_level_db** = ``-6.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -215,7 +215,7 @@ Sound level for the first tap. .. rst-class:: classref-property -:ref:`float` **tap1_pan** = ``0.2`` +:ref:`float` **tap1_pan** = ``0.2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -232,7 +232,7 @@ Pan position for the first tap. Value can range from -1 (fully left) to 1 (fully .. rst-class:: classref-property -:ref:`bool` **tap2_active** = ``true`` +:ref:`bool` **tap2_active** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -249,7 +249,7 @@ If ``true``, the second tap will be enabled. .. rst-class:: classref-property -:ref:`float` **tap2_delay_ms** = ``500.0`` +:ref:`float` **tap2_delay_ms** = ``500.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -266,7 +266,7 @@ Second tap delay time in milliseconds. .. rst-class:: classref-property -:ref:`float` **tap2_level_db** = ``-12.0`` +:ref:`float` **tap2_level_db** = ``-12.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -283,7 +283,7 @@ Sound level for the second tap. .. rst-class:: classref-property -:ref:`float` **tap2_pan** = ``-0.4`` +:ref:`float` **tap2_pan** = ``-0.4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -293,6 +293,7 @@ Sound level for the second tap. Pan position for the second tap. Value can range from -1 (fully left) to 1 (fully right). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectdistortion.rst b/classes/class_audioeffectdistortion.rst index df9d138c7ec..9724fae5dce 100644 --- a/classes/class_audioeffectdistortion.rst +++ b/classes/class_audioeffectdistortion.rst @@ -65,7 +65,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **Mode**: +enum **Mode**: :ref:`🔗` .. _class_AudioEffectDistortion_constant_MODE_CLIP: @@ -124,7 +124,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **drive** = ``0.0`` +:ref:`float` **drive** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -141,7 +141,7 @@ Distortion power. Value can range from 0 to 1. .. rst-class:: classref-property -:ref:`float` **keep_hf_hz** = ``16000.0`` +:ref:`float` **keep_hf_hz** = ``16000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -158,7 +158,7 @@ High-pass filter, in Hz. Frequencies higher than this value will not be affected .. rst-class:: classref-property -:ref:`Mode` **mode** = ``0`` +:ref:`Mode` **mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -175,7 +175,7 @@ Distortion type. .. rst-class:: classref-property -:ref:`float` **post_gain** = ``0.0`` +:ref:`float` **post_gain** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -192,7 +192,7 @@ Increases or decreases the volume after the effect, in decibels. Value can range .. rst-class:: classref-property -:ref:`float` **pre_gain** = ``0.0`` +:ref:`float` **pre_gain** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -202,6 +202,7 @@ Increases or decreases the volume after the effect, in decibels. Value can range Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffecteq.rst b/classes/class_audioeffecteq.rst index 6115db78170..b2d3eb11077 100644 --- a/classes/class_audioeffecteq.rst +++ b/classes/class_audioeffecteq.rst @@ -61,7 +61,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`int` **get_band_count**\ (\ ) |const| +:ref:`int` **get_band_count**\ (\ ) |const| :ref:`🔗` Returns the number of bands of the equalizer. @@ -73,7 +73,7 @@ Returns the number of bands of the equalizer. .. rst-class:: classref-method -:ref:`float` **get_band_gain_db**\ (\ band_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_band_gain_db**\ (\ band_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the band's gain at the specified index, in dB. @@ -85,11 +85,12 @@ Returns the band's gain at the specified index, in dB. .. rst-class:: classref-method -|void| **set_band_gain_db**\ (\ band_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) +|void| **set_band_gain_db**\ (\ band_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` Sets band's gain at the specified index, in dB. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffecteq10.rst b/classes/class_audioeffecteq10.rst index fe6ec7273cd..fab663d26c3 100644 --- a/classes/class_audioeffecteq10.rst +++ b/classes/class_audioeffecteq10.rst @@ -53,6 +53,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffecteq21.rst b/classes/class_audioeffecteq21.rst index d7dcd58ee04..403e88699d6 100644 --- a/classes/class_audioeffecteq21.rst +++ b/classes/class_audioeffecteq21.rst @@ -75,6 +75,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffecteq6.rst b/classes/class_audioeffecteq6.rst index 139c4c25cf2..a0c8de1cc31 100644 --- a/classes/class_audioeffecteq6.rst +++ b/classes/class_audioeffecteq6.rst @@ -45,6 +45,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectfilter.rst b/classes/class_audioeffectfilter.rst index a102ead0e2c..0f177335876 100644 --- a/classes/class_audioeffectfilter.rst +++ b/classes/class_audioeffectfilter.rst @@ -61,7 +61,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FilterDB**: +enum **FilterDB**: :ref:`🔗` .. _class_AudioEffectFilter_constant_FILTER_6DB: @@ -69,11 +69,7 @@ enum **FilterDB**: :ref:`FilterDB` **FILTER_6DB** = ``0`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 6dB per octave. .. _class_AudioEffectFilter_constant_FILTER_12DB: @@ -81,11 +77,7 @@ enum **FilterDB**: :ref:`FilterDB` **FILTER_12DB** = ``1`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 12dB per octave. .. _class_AudioEffectFilter_constant_FILTER_18DB: @@ -93,11 +85,7 @@ enum **FilterDB**: :ref:`FilterDB` **FILTER_18DB** = ``2`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 18dB per octave. .. _class_AudioEffectFilter_constant_FILTER_24DB: @@ -105,11 +93,7 @@ enum **FilterDB**: :ref:`FilterDB` **FILTER_24DB** = ``3`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 24dB per octave. .. rst-class:: classref-section-separator @@ -124,7 +108,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **cutoff_hz** = ``2000.0`` +:ref:`float` **cutoff_hz** = ``2000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -141,16 +125,14 @@ Threshold frequency for the filter, in Hz. .. rst-class:: classref-property -:ref:`FilterDB` **db** = ``0`` +:ref:`FilterDB` **db** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_db**\ (\ value\: :ref:`FilterDB`\ ) - :ref:`FilterDB` **get_db**\ (\ ) -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff. .. rst-class:: classref-item-separator @@ -160,7 +142,7 @@ Threshold frequency for the filter, in Hz. .. rst-class:: classref-property -:ref:`float` **gain** = ``1.0`` +:ref:`float` **gain** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -177,7 +159,7 @@ Gain amount of the frequencies after the filter. .. rst-class:: classref-property -:ref:`float` **resonance** = ``0.5`` +:ref:`float` **resonance** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -187,6 +169,7 @@ Gain amount of the frequencies after the filter. Amount of boost in the frequency range near the cutoff frequency. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffecthardlimiter.rst b/classes/class_audioeffecthardlimiter.rst new file mode 100644 index 00000000000..3620fdd7967 --- /dev/null +++ b/classes/class_audioeffecthardlimiter.rst @@ -0,0 +1,113 @@ +: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/AudioEffectHardLimiter.xml. + +.. _class_AudioEffectHardLimiter: + +AudioEffectHardLimiter +====================== + +**Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Adds a hard limiter audio effect to an Audio bus. + +.. rst-class:: classref-introduction-group + +Description +----------- + +A limiter is an effect designed to disallow sound from going over a given dB threshold. Hard limiters predict volume peaks, and will smoothly apply gain reduction when a peak crosses the ceiling threshold to prevent clipping and distortion. It preserves the waveform and prevents it from crossing the ceiling threshold. Adding one in the Master bus is recommended as a safety measure to prevent sudden volume peaks from occurring, and to prevent distortion caused by clipping. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Audio buses <../tutorials/audio/audio_buses>` + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+-----------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`ceiling_db` | ``-0.3`` | + +---------------------------+-----------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`pre_gain_db` | ``0.0`` | + +---------------------------+-----------------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`release` | ``0.1`` | + +---------------------------+-----------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioEffectHardLimiter_property_ceiling_db: + +.. rst-class:: classref-property + +:ref:`float` **ceiling_db** = ``-0.3`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_ceiling_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_ceiling_db**\ (\ ) + +The waveform's maximum allowed value, in decibels. This value can range from ``-24.0`` to ``0.0``. + +The default value of ``-0.3`` prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectHardLimiter_property_pre_gain_db: + +.. rst-class:: classref-property + +:ref:`float` **pre_gain_db** = ``0.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_pre_gain_db**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_pre_gain_db**\ (\ ) + +Gain to apply before limiting, in decibels. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioEffectHardLimiter_property_release: + +.. rst-class:: classref-property + +:ref:`float` **release** = ``0.1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_release**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_release**\ (\ ) + +Time it takes in seconds for the gain reduction to fully release. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioeffecthighpassfilter.rst b/classes/class_audioeffecthighpassfilter.rst index 3d5763b3d17..8c480cb82af 100644 --- a/classes/class_audioeffecthighpassfilter.rst +++ b/classes/class_audioeffecthighpassfilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffecthighshelffilter.rst b/classes/class_audioeffecthighshelffilter.rst index 11dc4176862..7c7e01d55ba 100644 --- a/classes/class_audioeffecthighshelffilter.rst +++ b/classes/class_audioeffecthighshelffilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectinstance.rst b/classes/class_audioeffectinstance.rst index 199ca3f9dc5..6d55bf36234 100644 --- a/classes/class_audioeffectinstance.rst +++ b/classes/class_audioeffectinstance.rst @@ -21,7 +21,7 @@ Manipulates the audio it receives for a given effect. Description ----------- -An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an :ref:`AudioEffect` when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with :ref:`AudioServer.get_bus_effect_instance`. +An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an :ref:`AudioEffect` when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with :ref:`AudioServer.get_bus_effect_instance()`. .. rst-class:: classref-introduction-group @@ -38,11 +38,11 @@ Methods .. table:: :widths: auto - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_process`\ (\ src_buffer\: ``const void*``, dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`_process_silence`\ (\ ) |virtual| |const| | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_process`\ (\ src_buffer\: ``const void*``, dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| | + +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_process_silence`\ (\ ) |virtual| |const| | + +-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -57,9 +57,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **_process**\ (\ src_buffer\: ``const void*``, dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| +|void| **_process**\ (\ src_buffer\: ``const void*``, dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| :ref:`🔗` -Called by the :ref:`AudioServer` to process this effect. When :ref:`_process_silence` is not overridden or it returns ``false``, this method is called only when the bus is active. +Called by the :ref:`AudioServer` to process this effect. When :ref:`_process_silence()` is not overridden or it returns ``false``, this method is called only when the bus is active. \ **Note:** It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. @@ -71,13 +71,14 @@ Called by the :ref:`AudioServer` to process this effect. When .. rst-class:: classref-method -:ref:`bool` **_process_silence**\ (\ ) |virtual| |const| +:ref:`bool` **_process_silence**\ (\ ) |virtual| |const| :ref:`🔗` Override this method to customize the processing behavior of this effect instance. -Should return ``true`` to force the :ref:`AudioServer` to always call :ref:`_process`, even if the bus has been muted or cannot otherwise be heard. +Should return ``true`` to force the :ref:`AudioServer` to always call :ref:`_process()`, even if the bus has been muted or cannot otherwise be heard. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectlimiter.rst b/classes/class_audioeffectlimiter.rst index 2b60bae0664..0a9b64b546b 100644 --- a/classes/class_audioeffectlimiter.rst +++ b/classes/class_audioeffectlimiter.rst @@ -10,6 +10,8 @@ AudioEffectLimiter ================== +**Deprecated:** Use :ref:`AudioEffectHardLimiter` instead. + **Inherits:** :ref:`AudioEffect` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Adds a soft-clip limiter audio effect to an Audio bus. @@ -61,7 +63,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **ceiling_db** = ``-0.1`` +:ref:`float` **ceiling_db** = ``-0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -78,7 +80,7 @@ The waveform's maximum allowed value, in decibels. Value can range from -20 to - .. rst-class:: classref-property -:ref:`float` **soft_clip_db** = ``2.0`` +:ref:`float` **soft_clip_db** = ``2.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -95,7 +97,7 @@ Applies a gain to the limited waves, in decibels. Value can range from 0 to 6. .. rst-class:: classref-property -:ref:`float` **soft_clip_ratio** = ``10.0`` +:ref:`float` **soft_clip_ratio** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -114,7 +116,7 @@ Applies a gain to the limited waves, in decibels. Value can range from 0 to 6. .. rst-class:: classref-property -:ref:`float` **threshold_db** = ``0.0`` +:ref:`float` **threshold_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -124,6 +126,7 @@ Applies a gain to the limited waves, in decibels. Value can range from 0 to 6. Threshold from which the limiter begins to be active, in decibels. Value can range from -30 to 0. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectlowpassfilter.rst b/classes/class_audioeffectlowpassfilter.rst index bcf0160b80c..6975557b248 100644 --- a/classes/class_audioeffectlowpassfilter.rst +++ b/classes/class_audioeffectlowpassfilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectlowshelffilter.rst b/classes/class_audioeffectlowshelffilter.rst index f42fcbdf468..33e2b5653f6 100644 --- a/classes/class_audioeffectlowshelffilter.rst +++ b/classes/class_audioeffectlowshelffilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectnotchfilter.rst b/classes/class_audioeffectnotchfilter.rst index d7d6847e519..d701c1b46bc 100644 --- a/classes/class_audioeffectnotchfilter.rst +++ b/classes/class_audioeffectnotchfilter.rst @@ -29,6 +29,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectpanner.rst b/classes/class_audioeffectpanner.rst index 1352091dc22..6927fb5b8d3 100644 --- a/classes/class_audioeffectpanner.rst +++ b/classes/class_audioeffectpanner.rst @@ -53,7 +53,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **pan** = ``0.0`` +:ref:`float` **pan** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -63,6 +63,7 @@ Property Descriptions Pan position. Value can range from -1 (fully left) to 1 (fully right). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectphaser.rst b/classes/class_audioeffectphaser.rst index 4d16c17beee..9f696b69b75 100644 --- a/classes/class_audioeffectphaser.rst +++ b/classes/class_audioeffectphaser.rst @@ -63,14 +63,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **depth** = ``1.0`` +:ref:`float` **depth** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_depth**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_depth**\ (\ ) -Governs how high the filter frequencies sweep. Low value will primarily affect bass frequencies. High value can sweep high into the treble. Value can range from 0.1 to 4. +Determines how high the filter frequencies sweep. Low value will primarily affect bass frequencies. High value can sweep high into the treble. Value can range from ``0.1`` to ``4.0``. .. rst-class:: classref-item-separator @@ -80,7 +80,7 @@ Governs how high the filter frequencies sweep. Low value will primarily affect b .. rst-class:: classref-property -:ref:`float` **feedback** = ``0.7`` +:ref:`float` **feedback** = ``0.7`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -97,7 +97,7 @@ Output percent of modified sound. Value can range from 0.1 to 0.9. .. rst-class:: classref-property -:ref:`float` **range_max_hz** = ``1600.0`` +:ref:`float` **range_max_hz** = ``1600.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -114,7 +114,7 @@ Determines the maximum frequency affected by the LFO modulations, in Hz. Value c .. rst-class:: classref-property -:ref:`float` **range_min_hz** = ``440.0`` +:ref:`float` **range_min_hz** = ``440.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -131,7 +131,7 @@ Determines the minimum frequency affected by the LFO modulations, in Hz. Value c .. rst-class:: classref-property -:ref:`float` **rate_hz** = ``0.5`` +:ref:`float` **rate_hz** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -141,6 +141,7 @@ Determines the minimum frequency affected by the LFO modulations, in Hz. Value c Adjusts the rate in Hz at which the effect sweeps up and down across the frequency range. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectpitchshift.rst b/classes/class_audioeffectpitchshift.rst index ca17f0d2099..bde396a6197 100644 --- a/classes/class_audioeffectpitchshift.rst +++ b/classes/class_audioeffectpitchshift.rst @@ -59,7 +59,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FFTSize**: +enum **FFTSize**: :ref:`🔗` .. _class_AudioEffectPitchShift_constant_FFT_SIZE_256: @@ -122,7 +122,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`FFTSize` **fft_size** = ``3`` +:ref:`FFTSize` **fft_size** = ``3`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -139,7 +139,7 @@ The size of the `Fast Fourier transform ` **oversampling** = ``4`` +:ref:`int` **oversampling** = ``4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -156,7 +156,7 @@ The oversampling factor to use. Higher values result in better quality, but are .. rst-class:: classref-property -:ref:`float` **pitch_scale** = ``1.0`` +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -166,6 +166,7 @@ The oversampling factor to use. Higher values result in better quality, but are The pitch scale to use. ``1.0`` is the default pitch and plays sounds unaffected. :ref:`pitch_scale` can range from ``0.0`` (infinitely low pitch, inaudible) to ``16`` (16 times higher than the initial pitch). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectrecord.rst b/classes/class_audioeffectrecord.rst index c344f946e32..cb5eccc6914 100644 --- a/classes/class_audioeffectrecord.rst +++ b/classes/class_audioeffectrecord.rst @@ -34,7 +34,7 @@ Tutorials - :doc:`Recording with microphone <../tutorials/audio/recording_with_microphone>` -- `Audio Mic Record Demo `__ +- `Audio Microphone Record Demo `__ .. rst-class:: classref-reftable-group @@ -77,14 +77,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Format` **format** = ``1`` +:ref:`Format` **format** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_format**\ (\ value\: :ref:`Format`\ ) - :ref:`Format` **get_format**\ (\ ) -Specifies the format in which the sample will be recorded. See :ref:`Format` for available formats. +Specifies the format in which the sample will be recorded. .. rst-class:: classref-section-separator @@ -99,7 +99,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`AudioStreamWAV` **get_recording**\ (\ ) |const| +:ref:`AudioStreamWAV` **get_recording**\ (\ ) |const| :ref:`🔗` Returns the recorded sample. @@ -111,7 +111,7 @@ Returns the recorded sample. .. rst-class:: classref-method -:ref:`bool` **is_recording_active**\ (\ ) |const| +:ref:`bool` **is_recording_active**\ (\ ) |const| :ref:`🔗` Returns whether the recording is active or not. @@ -123,11 +123,12 @@ Returns whether the recording is active or not. .. rst-class:: classref-method -|void| **set_recording_active**\ (\ record\: :ref:`bool`\ ) +|void| **set_recording_active**\ (\ record\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the sound will be recorded. Note that restarting the recording will remove the previously recorded sample. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectreverb.rst b/classes/class_audioeffectreverb.rst index a143ad17c22..7b82e1f9273 100644 --- a/classes/class_audioeffectreverb.rst +++ b/classes/class_audioeffectreverb.rst @@ -28,7 +28,7 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -69,7 +69,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **damping** = ``0.5`` +:ref:`float` **damping** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -86,7 +86,7 @@ Defines how reflective the imaginary room's walls are. Value can range from 0 to .. rst-class:: classref-property -:ref:`float` **dry** = ``1.0`` +:ref:`float` **dry** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -103,7 +103,7 @@ Output percent of original sound. At 0, only modified sound is outputted. Value .. rst-class:: classref-property -:ref:`float` **hipass** = ``0.0`` +:ref:`float` **hipass** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -120,7 +120,7 @@ High-pass filter passes signals with a frequency higher than a certain cutoff fr .. rst-class:: classref-property -:ref:`float` **predelay_feedback** = ``0.4`` +:ref:`float` **predelay_feedback** = ``0.4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -137,7 +137,7 @@ Output percent of predelay. Value can range from 0 to 1. .. rst-class:: classref-property -:ref:`float` **predelay_msec** = ``150.0`` +:ref:`float` **predelay_msec** = ``150.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -154,7 +154,7 @@ Time between the original signal and the early reflections of the reverb signal, .. rst-class:: classref-property -:ref:`float` **room_size** = ``0.8`` +:ref:`float` **room_size** = ``0.8`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -171,7 +171,7 @@ Dimensions of simulated room. Bigger means more echoes. Value can range from 0 t .. rst-class:: classref-property -:ref:`float` **spread** = ``1.0`` +:ref:`float` **spread** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -188,7 +188,7 @@ Widens or narrows the stereo image of the reverb tail. 1 means fully widens. Val .. rst-class:: classref-property -:ref:`float` **wet** = ``0.5`` +:ref:`float` **wet** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,6 +198,7 @@ Widens or narrows the stereo image of the reverb tail. 1 means fully widens. Val Output percent of modified sound. At 0, only original sound is outputted. Value can range from 0 to 1. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectspectrumanalyzer.rst b/classes/class_audioeffectspectrumanalyzer.rst index 8db1a9f7fe9..165c49caf3e 100644 --- a/classes/class_audioeffectspectrumanalyzer.rst +++ b/classes/class_audioeffectspectrumanalyzer.rst @@ -21,6 +21,8 @@ Description This audio effect does not affect sound output, but can be used for real-time audio visualizations. +This resource configures an :ref:`AudioEffectSpectrumAnalyzerInstance`, which performs the actual analysis at runtime. An instance can be obtained with :ref:`AudioServer.get_bus_effect_instance()`. + See also :ref:`AudioStreamGenerator` for procedurally generating sounds. .. rst-class:: classref-introduction-group @@ -28,9 +30,7 @@ See also :ref:`AudioStreamGenerator` for procedurall Tutorials --------- -- `Audio Spectrum Demo `__ - -- `Godot 3.2 will get new audio features `__ +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -61,7 +61,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FFTSize**: +enum **FFTSize**: :ref:`🔗` .. _class_AudioEffectSpectrumAnalyzer_constant_FFT_SIZE_256: @@ -124,7 +124,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **buffer_length** = ``2.0`` +:ref:`float` **buffer_length** = ``2.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -141,7 +141,7 @@ The length of the buffer to keep (in seconds). Higher values keep data around fo .. rst-class:: classref-property -:ref:`FFTSize` **fft_size** = ``2`` +:ref:`FFTSize` **fft_size** = ``2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -158,7 +158,7 @@ The size of the `Fast Fourier transform ` **tap_back_pos** = ``0.01`` +:ref:`float` **tap_back_pos** = ``0.01`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -170,6 +170,7 @@ The size of the `Fast Fourier transform `! .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectspectrumanalyzerinstance.rst b/classes/class_audioeffectspectrumanalyzerinstance.rst index 703ab024faa..bcabc22201a 100644 --- a/classes/class_audioeffectspectrumanalyzerinstance.rst +++ b/classes/class_audioeffectspectrumanalyzerinstance.rst @@ -12,9 +12,23 @@ AudioEffectSpectrumAnalyzerInstance **Inherits:** :ref:`AudioEffectInstance` **<** :ref:`RefCounted` **<** :ref:`Object` -.. container:: contribute +Queryable instance of an :ref:`AudioEffectSpectrumAnalyzer`. - There is currently no description for this class. Please help us by :ref:`contributing one `! +.. rst-class:: classref-introduction-group + +Description +----------- + +The runtime part of an :ref:`AudioEffectSpectrumAnalyzer`, which can be used to query the magnitude of a frequency range on its host bus. + +An instance of this class can be obtained with :ref:`AudioServer.get_bus_effect_instance()`. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -41,7 +55,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **MagnitudeMode**: +enum **MagnitudeMode**: :ref:`🔗` .. _class_AudioEffectSpectrumAnalyzerInstance_constant_MAGNITUDE_AVERAGE: @@ -49,7 +63,7 @@ enum **MagnitudeMode**: :ref:`MagnitudeMode` **MAGNITUDE_AVERAGE** = ``0`` -Use the average value as magnitude. +Use the average value across the frequency range as magnitude. .. _class_AudioEffectSpectrumAnalyzerInstance_constant_MAGNITUDE_MAX: @@ -57,7 +71,7 @@ Use the average value as magnitude. :ref:`MagnitudeMode` **MAGNITUDE_MAX** = ``1`` -Use the maximum value as magnitude. +Use the maximum value of the frequency range as magnitude. .. rst-class:: classref-section-separator @@ -72,13 +86,14 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Vector2` **get_magnitude_for_frequency_range**\ (\ from_hz\: :ref:`float`, to_hz\: :ref:`float`, mode\: :ref:`MagnitudeMode` = 1\ ) |const| +:ref:`Vector2` **get_magnitude_for_frequency_range**\ (\ from_hz\: :ref:`float`, to_hz\: :ref:`float`, mode\: :ref:`MagnitudeMode` = 1\ ) |const| :ref:`🔗` -.. container:: contribute +Returns the magnitude of the frequencies from ``from_hz`` to ``to_hz`` in linear energy as a Vector2. The ``x`` component of the return value represents the left stereo channel, and ``y`` represents the right channel. - There is currently no description for this method. Please help us by :ref:`contributing one `! +\ ``mode`` determines how the frequency range will be processed. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audioeffectstereoenhance.rst b/classes/class_audioeffectstereoenhance.rst index 50474394b4e..7d492e9ca5b 100644 --- a/classes/class_audioeffectstereoenhance.rst +++ b/classes/class_audioeffectstereoenhance.rst @@ -57,14 +57,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **pan_pullout** = ``1.0`` +:ref:`float` **pan_pullout** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_pan_pullout**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_pan_pullout**\ (\ ) -Values greater than 1.0 increase intensity of any panning on audio passing through this effect, whereas values less than 1.0 will decrease the panning intensity. A value of 0.0 will downmix audio to mono. +Amplifies the difference between stereo channels, increasing or decreasing existing panning. A value of 0.0 will downmix stereo to mono. Does not affect a mono signal. .. rst-class:: classref-item-separator @@ -74,16 +74,14 @@ Values greater than 1.0 increase intensity of any panning on audio passing throu .. rst-class:: classref-property -:ref:`float` **surround** = ``0.0`` +:ref:`float` **surround** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_surround**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_surround**\ (\ ) -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Widens sound stage through phase shifting in conjunction with :ref:`time_pullout_ms`. Just pans sound to the left channel if :ref:`time_pullout_ms` is 0. .. rst-class:: classref-item-separator @@ -93,18 +91,17 @@ Values greater than 1.0 increase intensity of any panning on audio passing throu .. rst-class:: classref-property -:ref:`float` **time_pullout_ms** = ``0.0`` +:ref:`float` **time_pullout_ms** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_time_pullout**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_time_pullout**\ (\ ) -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Widens sound stage through phase shifting in conjunction with :ref:`surround`. Just delays the right channel if :ref:`surround` is 0. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiolistener2d.rst b/classes/class_audiolistener2d.rst index da5bbfd1de2..1d9d0da1d2c 100644 --- a/classes/class_audiolistener2d.rst +++ b/classes/class_audiolistener2d.rst @@ -22,7 +22,7 @@ Overrides the location sounds are heard from. Description ----------- -Once added to the scene tree and enabled using :ref:`make_current`, this node will override the location sounds are heard from. Only one **AudioListener2D** can be current. Using :ref:`make_current` will disable the previous **AudioListener2D**. +Once added to the scene tree and enabled using :ref:`make_current()`, this node will override the location sounds are heard from. Only one **AudioListener2D** can be current. Using :ref:`make_current()` will disable the previous **AudioListener2D**. If there is no active **AudioListener2D** in the current :ref:`Viewport`, center of the screen will be used as a hearing point for the audio. **AudioListener2D** needs to be inside :ref:`SceneTree` to function. @@ -55,7 +55,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **clear_current**\ (\ ) +|void| **clear_current**\ (\ ) :ref:`🔗` Disables the **AudioListener2D**. If it's not set as current, this method will have no effect. @@ -67,7 +67,7 @@ Disables the **AudioListener2D**. If it's not set as current, this method will h .. rst-class:: classref-method -:ref:`bool` **is_current**\ (\ ) |const| +:ref:`bool` **is_current**\ (\ ) |const| :ref:`🔗` Returns ``true`` if this **AudioListener2D** is currently active. @@ -79,13 +79,14 @@ Returns ``true`` if this **AudioListener2D** is currently active. .. rst-class:: classref-method -|void| **make_current**\ (\ ) +|void| **make_current**\ (\ ) :ref:`🔗` Makes the **AudioListener2D** active, setting it as the hearing point for the sounds. If there is already another active **AudioListener2D**, it will be disabled. This method will have no effect if the **AudioListener2D** is not added to :ref:`SceneTree`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiolistener3d.rst b/classes/class_audiolistener3d.rst index 2138839f322..5bc0d1f88c0 100644 --- a/classes/class_audiolistener3d.rst +++ b/classes/class_audiolistener3d.rst @@ -22,7 +22,19 @@ Overrides the location sounds are heard from. Description ----------- -Once added to the scene tree and enabled using :ref:`make_current`, this node will override the location sounds are heard from. This can be used to listen from a location different from the :ref:`Camera3D`. +Once added to the scene tree and enabled using :ref:`make_current()`, this node will override the location sounds are heard from. This can be used to listen from a location different from the :ref:`Camera3D`. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +--------------------------------------------------------------+--------------------------------------------------------------------------+-------+ + | :ref:`DopplerTracking` | :ref:`doppler_tracking` | ``0`` | + +--------------------------------------------------------------+--------------------------------------------------------------------------+-------+ .. rst-class:: classref-reftable-group @@ -48,6 +60,69 @@ Methods .. rst-class:: classref-descriptions-group +Enumerations +------------ + +.. _enum_AudioListener3D_DopplerTracking: + +.. rst-class:: classref-enumeration + +enum **DopplerTracking**: :ref:`🔗` + +.. _class_AudioListener3D_constant_DOPPLER_TRACKING_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_DISABLED** = ``0`` + +Disables `Doppler effect `__ simulation (default). + +.. _class_AudioListener3D_constant_DOPPLER_TRACKING_IDLE_STEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_IDLE_STEP** = ``1`` + +Simulate `Doppler effect `__ by tracking positions of objects that are changed in ``_process``. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's :ref:`AudioStreamPlayer3D.pitch_scale`). + +.. _class_AudioListener3D_constant_DOPPLER_TRACKING_PHYSICS_STEP: + +.. rst-class:: classref-enumeration-constant + +:ref:`DopplerTracking` **DOPPLER_TRACKING_PHYSICS_STEP** = ``2`` + +Simulate `Doppler effect `__ by tracking positions of objects that are changed in ``_physics_process``. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's :ref:`AudioStreamPlayer3D.pitch_scale`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioListener3D_property_doppler_tracking: + +.. rst-class:: classref-property + +:ref:`DopplerTracking` **doppler_tracking** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_doppler_tracking**\ (\ value\: :ref:`DopplerTracking`\ ) +- :ref:`DopplerTracking` **get_doppler_tracking**\ (\ ) + +If not :ref:`DOPPLER_TRACKING_DISABLED`, this listener will simulate the `Doppler effect `__ for objects changed in particular ``_process`` methods. + +\ **Note:** The Doppler effect will only be heard on :ref:`AudioStreamPlayer3D`\ s if :ref:`AudioStreamPlayer3D.doppler_tracking` is not set to :ref:`AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED`. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- @@ -55,7 +130,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **clear_current**\ (\ ) +|void| **clear_current**\ (\ ) :ref:`🔗` Disables the listener to use the current camera's listener instead. @@ -67,7 +142,7 @@ Disables the listener to use the current camera's listener instead. .. rst-class:: classref-method -:ref:`Transform3D` **get_listener_transform**\ (\ ) |const| +:ref:`Transform3D` **get_listener_transform**\ (\ ) |const| :ref:`🔗` Returns the listener's global orthonormalized :ref:`Transform3D`. @@ -79,9 +154,9 @@ Returns the listener's global orthonormalized :ref:`Transform3D` **is_current**\ (\ ) |const| +:ref:`bool` **is_current**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the listener was made current using :ref:`make_current`, ``false`` otherwise. +Returns ``true`` if the listener was made current using :ref:`make_current()`, ``false`` otherwise. \ **Note:** There may be more than one AudioListener3D marked as "current" in the scene tree, but only the one that was made current last will be used. @@ -93,11 +168,12 @@ Returns ``true`` if the listener was made current using :ref:`make_current` Enables the listener. This will override the current camera's listener. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiosample.rst b/classes/class_audiosample.rst new file mode 100644 index 00000000000..76b59731696 --- /dev/null +++ b/classes/class_audiosample.rst @@ -0,0 +1,34 @@ +: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/AudioSample.xml. + +.. _class_AudioSample: + +AudioSample +=========== + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +Base class for audio samples. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class for audio samples. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiosampleplayback.rst b/classes/class_audiosampleplayback.rst new file mode 100644 index 00000000000..ea722e18d2c --- /dev/null +++ b/classes/class_audiosampleplayback.rst @@ -0,0 +1,34 @@ +: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/AudioSamplePlayback.xml. + +.. _class_AudioSamplePlayback: + +AudioSamplePlayback +=================== + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** :ref:`RefCounted` **<** :ref:`Object` + +Meta class for playing back audio samples. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Meta class for playing back audio samples. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audioserver.rst b/classes/class_audioserver.rst index 7d94051428c..45d8a6efcb5 100644 --- a/classes/class_audioserver.rst +++ b/classes/class_audioserver.rst @@ -28,11 +28,11 @@ Tutorials - :doc:`Audio buses <../tutorials/audio/audio_buses>` -- `Audio Device Changer Demo `__ +- `Audio Device Changer Demo `__ -- `Audio Mic Record Demo `__ +- `Audio Microphone Record Demo `__ -- `Audio Spectrum Demo `__ +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -87,8 +87,14 @@ Methods +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_bus_volume_db`\ (\ bus_idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bus_volume_linear`\ (\ bus_idx\: :ref:`int`\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_driver_name`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`get_input_device_list`\ (\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_input_mix_rate`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_mix_rate`\ (\ ) |const| | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`get_output_device_list`\ (\ ) | @@ -109,10 +115,14 @@ Methods +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_bus_solo`\ (\ bus_idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_stream_registered_as_sample`\ (\ stream\: :ref:`AudioStream`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`lock`\ (\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`move_bus`\ (\ index\: :ref:`int`, to_index\: :ref:`int`\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`register_stream_as_sample`\ (\ stream\: :ref:`AudioStream`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_bus`\ (\ index\: :ref:`int`\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_bus_effect`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) | @@ -133,6 +143,8 @@ Methods +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_bus_volume_db`\ (\ bus_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_bus_volume_linear`\ (\ bus_idx\: :ref:`int`, volume_linear\: :ref:`float`\ ) | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_enable_tagging_used_audio_streams`\ (\ enable\: :ref:`bool`\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`swap_bus_effects`\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, by_effect_idx\: :ref:`int`\ ) | @@ -153,7 +165,7 @@ Signals .. rst-class:: classref-signal -**bus_layout_changed**\ (\ ) +**bus_layout_changed**\ (\ ) :ref:`🔗` Emitted when an audio bus is added, deleted, or moved. @@ -165,7 +177,7 @@ Emitted when an audio bus is added, deleted, or moved. .. rst-class:: classref-signal -**bus_renamed**\ (\ bus_index\: :ref:`int`, old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) +**bus_renamed**\ (\ bus_index\: :ref:`int`, old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` Emitted when the audio bus at ``bus_index`` is renamed from ``old_name`` to ``new_name``. @@ -182,7 +194,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **SpeakerMode**: +enum **SpeakerMode**: :ref:`🔗` .. _class_AudioServer_constant_SPEAKER_MODE_STEREO: @@ -216,6 +228,60 @@ A 5.1 channel surround setup was detected. A 7.1 channel surround setup was detected. +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioServer_PlaybackType: + +.. rst-class:: classref-enumeration + +enum **PlaybackType**: :ref:`🔗` + +.. _class_AudioServer_constant_PLAYBACK_TYPE_DEFAULT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_DEFAULT** = ``0`` + +**Experimental:** This constant may be changed or removed in future versions. + +The playback will be considered of the type declared at :ref:`ProjectSettings.audio/general/default_playback_type`. + +.. _class_AudioServer_constant_PLAYBACK_TYPE_STREAM: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_STREAM** = ``1`` + +**Experimental:** This constant may be changed or removed in future versions. + +Force the playback to be considered as a stream. + +.. _class_AudioServer_constant_PLAYBACK_TYPE_SAMPLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_SAMPLE** = ``2`` + +**Experimental:** This constant may be changed or removed in future versions. + +Force the playback to be considered as a sample. This can provide lower latency and more stable playback (with less risk of audio crackling), at the cost of having less flexibility. + +\ **Note:** Only currently supported on the web platform. + +\ **Note:** :ref:`AudioEffect`\ s are not supported when playback is considered as a sample. + +.. _class_AudioServer_constant_PLAYBACK_TYPE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`PlaybackType` **PLAYBACK_TYPE_MAX** = ``3`` + +**Experimental:** This constant may be changed or removed in future versions. + +Represents the size of the :ref:`PlaybackType` enum. + .. rst-class:: classref-section-separator ---- @@ -229,7 +295,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **bus_count** = ``1`` +:ref:`int` **bus_count** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -246,14 +312,14 @@ Number of available audio buses. .. rst-class:: classref-property -:ref:`String` **input_device** = ``"Default"`` +:ref:`String` **input_device** = ``"Default"`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_input_device**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_input_device**\ (\ ) -Name of the current device for audio input (see :ref:`get_input_device_list`). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value ``"Default"`` will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to ``"Default"``. +Name of the current device for audio input (see :ref:`get_input_device_list()`). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value ``"Default"`` will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to ``"Default"``. \ **Note:** :ref:`ProjectSettings.audio/driver/enable_input` must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. @@ -265,14 +331,14 @@ Name of the current device for audio input (see :ref:`get_input_device_list` **output_device** = ``"Default"`` +:ref:`String` **output_device** = ``"Default"`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_output_device**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_output_device**\ (\ ) -Name of the current device for audio output (see :ref:`get_output_device_list`). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value ``"Default"`` will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to ``"Default"``. +Name of the current device for audio output (see :ref:`get_output_device_list()`). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value ``"Default"`` will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to ``"Default"``. .. rst-class:: classref-item-separator @@ -282,7 +348,7 @@ Name of the current device for audio output (see :ref:`get_output_device_list` **playback_speed_scale** = ``1.0`` +:ref:`float` **playback_speed_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -304,7 +370,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_bus**\ (\ at_position\: :ref:`int` = -1\ ) +|void| **add_bus**\ (\ at_position\: :ref:`int` = -1\ ) :ref:`🔗` Adds a bus at ``at_position``. @@ -316,7 +382,7 @@ Adds a bus at ``at_position``. .. rst-class:: classref-method -|void| **add_bus_effect**\ (\ bus_idx\: :ref:`int`, effect\: :ref:`AudioEffect`, at_position\: :ref:`int` = -1\ ) +|void| **add_bus_effect**\ (\ bus_idx\: :ref:`int`, effect\: :ref:`AudioEffect`, at_position\: :ref:`int` = -1\ ) :ref:`🔗` Adds an :ref:`AudioEffect` effect to the bus ``bus_idx`` at ``at_position``. @@ -328,7 +394,7 @@ Adds an :ref:`AudioEffect` effect to the bus ``bus_idx`` at ` .. rst-class:: classref-method -:ref:`AudioBusLayout` **generate_bus_layout**\ (\ ) |const| +:ref:`AudioBusLayout` **generate_bus_layout**\ (\ ) |const| :ref:`🔗` Generates an :ref:`AudioBusLayout` using the available buses and effects. @@ -340,7 +406,7 @@ Generates an :ref:`AudioBusLayout` using the available bus .. rst-class:: classref-method -:ref:`int` **get_bus_channels**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`int` **get_bus_channels**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the number of channels of the bus at index ``bus_idx``. @@ -352,7 +418,7 @@ Returns the number of channels of the bus at index ``bus_idx``. .. rst-class:: classref-method -:ref:`AudioEffect` **get_bus_effect**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) +:ref:`AudioEffect` **get_bus_effect**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) :ref:`🔗` Returns the :ref:`AudioEffect` at position ``effect_idx`` in bus ``bus_idx``. @@ -364,7 +430,7 @@ Returns the :ref:`AudioEffect` at position ``effect_idx`` in .. rst-class:: classref-method -:ref:`int` **get_bus_effect_count**\ (\ bus_idx\: :ref:`int`\ ) +:ref:`int` **get_bus_effect_count**\ (\ bus_idx\: :ref:`int`\ ) :ref:`🔗` Returns the number of effects on the bus at ``bus_idx``. @@ -376,7 +442,7 @@ Returns the number of effects on the bus at ``bus_idx``. .. rst-class:: classref-method -:ref:`AudioEffectInstance` **get_bus_effect_instance**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, channel\: :ref:`int` = 0\ ) +:ref:`AudioEffectInstance` **get_bus_effect_instance**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, channel\: :ref:`int` = 0\ ) :ref:`🔗` Returns the :ref:`AudioEffectInstance` assigned to the given bus and effect indices (and optionally channel). @@ -388,7 +454,7 @@ Returns the :ref:`AudioEffectInstance` assigned to th .. rst-class:: classref-method -:ref:`int` **get_bus_index**\ (\ bus_name\: :ref:`StringName`\ ) |const| +:ref:`int` **get_bus_index**\ (\ bus_name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the index of the bus with the name ``bus_name``. Returns ``-1`` if no bus with the specified name exist. @@ -400,7 +466,7 @@ Returns the index of the bus with the name ``bus_name``. Returns ``-1`` if no bu .. rst-class:: classref-method -:ref:`String` **get_bus_name**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`String` **get_bus_name**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the name of the bus with the index ``bus_idx``. @@ -412,7 +478,7 @@ Returns the name of the bus with the index ``bus_idx``. .. rst-class:: classref-method -:ref:`float` **get_bus_peak_volume_left_db**\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| +:ref:`float` **get_bus_peak_volume_left_db**\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| :ref:`🔗` Returns the peak volume of the left speaker at bus index ``bus_idx`` and channel index ``channel``. @@ -424,7 +490,7 @@ Returns the peak volume of the left speaker at bus index ``bus_idx`` and channel .. rst-class:: classref-method -:ref:`float` **get_bus_peak_volume_right_db**\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| +:ref:`float` **get_bus_peak_volume_right_db**\ (\ bus_idx\: :ref:`int`, channel\: :ref:`int`\ ) |const| :ref:`🔗` Returns the peak volume of the right speaker at bus index ``bus_idx`` and channel index ``channel``. @@ -436,7 +502,7 @@ Returns the peak volume of the right speaker at bus index ``bus_idx`` and channe .. rst-class:: classref-method -:ref:`StringName` **get_bus_send**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`StringName` **get_bus_send**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the name of the bus that the bus at index ``bus_idx`` sends to. @@ -448,7 +514,7 @@ Returns the name of the bus that the bus at index ``bus_idx`` sends to. .. rst-class:: classref-method -:ref:`float` **get_bus_volume_db**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`float` **get_bus_volume_db**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` Returns the volume of the bus at index ``bus_idx`` in dB. @@ -456,11 +522,37 @@ Returns the volume of the bus at index ``bus_idx`` in dB. ---- +.. _class_AudioServer_method_get_bus_volume_linear: + +.. rst-class:: classref-method + +:ref:`float` **get_bus_volume_linear**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the volume of the bus at index ``bus_idx`` as a linear value. + +\ **Note:** The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on the result of :ref:`get_bus_volume_db()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_get_driver_name: + +.. rst-class:: classref-method + +:ref:`String` **get_driver_name**\ (\ ) |const| :ref:`🔗` + +Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the ``--audio-driver`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>`. ``--headless`` also automatically sets the audio driver to ``Dummy``. See also :ref:`ProjectSettings.audio/driver/driver`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioServer_method_get_input_device_list: .. rst-class:: classref-method -:ref:`PackedStringArray` **get_input_device_list**\ (\ ) +:ref:`PackedStringArray` **get_input_device_list**\ (\ ) :ref:`🔗` Returns the names of all audio input devices detected on the system. @@ -470,11 +562,23 @@ Returns the names of all audio input devices detected on the system. ---- +.. _class_AudioServer_method_get_input_mix_rate: + +.. rst-class:: classref-method + +:ref:`float` **get_input_mix_rate**\ (\ ) |const| :ref:`🔗` + +Returns the sample rate at the input of the **AudioServer**. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioServer_method_get_mix_rate: .. rst-class:: classref-method -:ref:`float` **get_mix_rate**\ (\ ) |const| +:ref:`float` **get_mix_rate**\ (\ ) |const| :ref:`🔗` Returns the sample rate at the output of the **AudioServer**. @@ -486,7 +590,7 @@ Returns the sample rate at the output of the **AudioServer**. .. rst-class:: classref-method -:ref:`PackedStringArray` **get_output_device_list**\ (\ ) +:ref:`PackedStringArray` **get_output_device_list**\ (\ ) :ref:`🔗` Returns the names of all audio output devices detected on the system. @@ -498,11 +602,11 @@ Returns the names of all audio output devices detected on the system. .. rst-class:: classref-method -:ref:`float` **get_output_latency**\ (\ ) |const| +:ref:`float` **get_output_latency**\ (\ ) |const| :ref:`🔗` Returns the audio driver's effective output latency. This is based on :ref:`ProjectSettings.audio/driver/output_latency`, but the exact returned value will differ depending on the operating system and audio driver. -\ **Note:** This can be expensive; it is not recommended to call :ref:`get_output_latency` every frame. +\ **Note:** This can be expensive; it is not recommended to call :ref:`get_output_latency()` every frame. .. rst-class:: classref-item-separator @@ -512,7 +616,7 @@ Returns the audio driver's effective output latency. This is based on :ref:`Proj .. rst-class:: classref-method -:ref:`SpeakerMode` **get_speaker_mode**\ (\ ) |const| +:ref:`SpeakerMode` **get_speaker_mode**\ (\ ) |const| :ref:`🔗` Returns the speaker configuration. @@ -524,7 +628,7 @@ Returns the speaker configuration. .. rst-class:: classref-method -:ref:`float` **get_time_since_last_mix**\ (\ ) |const| +:ref:`float` **get_time_since_last_mix**\ (\ ) |const| :ref:`🔗` Returns the relative time since the last mix occurred. @@ -536,7 +640,7 @@ Returns the relative time since the last mix occurred. .. rst-class:: classref-method -:ref:`float` **get_time_to_next_mix**\ (\ ) |const| +:ref:`float` **get_time_to_next_mix**\ (\ ) |const| :ref:`🔗` Returns the relative time until the next mix occurs. @@ -548,7 +652,7 @@ Returns the relative time until the next mix occurs. .. rst-class:: classref-method -:ref:`bool` **is_bus_bypassing_effects**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`bool` **is_bus_bypassing_effects**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is bypassing effects. @@ -560,7 +664,7 @@ If ``true``, the bus at index ``bus_idx`` is bypassing effects. .. rst-class:: classref-method -:ref:`bool` **is_bus_effect_enabled**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) |const| +:ref:`bool` **is_bus_effect_enabled**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the effect at index ``effect_idx`` on the bus at index ``bus_idx`` is enabled. @@ -572,7 +676,7 @@ If ``true``, the effect at index ``effect_idx`` on the bus at index ``bus_idx`` .. rst-class:: classref-method -:ref:`bool` **is_bus_mute**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`bool` **is_bus_mute**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is muted. @@ -584,7 +688,7 @@ If ``true``, the bus at index ``bus_idx`` is muted. .. rst-class:: classref-method -:ref:`bool` **is_bus_solo**\ (\ bus_idx\: :ref:`int`\ ) |const| +:ref:`bool` **is_bus_solo**\ (\ bus_idx\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is in solo mode. @@ -592,11 +696,27 @@ If ``true``, the bus at index ``bus_idx`` is in solo mode. ---- +.. _class_AudioServer_method_is_stream_registered_as_sample: + +.. rst-class:: classref-method + +:ref:`bool` **is_stream_registered_as_sample**\ (\ stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +If ``true``, the stream is registered as a sample. The engine will not have to register it before playing the sample. + +If ``false``, the stream will have to be registered before playing it. To prevent lag spikes, register the stream as sample with :ref:`register_stream_as_sample()`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioServer_method_lock: .. rst-class:: classref-method -|void| **lock**\ (\ ) +|void| **lock**\ (\ ) :ref:`🔗` Locks the audio driver's main loop. @@ -610,7 +730,7 @@ Locks the audio driver's main loop. .. rst-class:: classref-method -|void| **move_bus**\ (\ index\: :ref:`int`, to_index\: :ref:`int`\ ) +|void| **move_bus**\ (\ index\: :ref:`int`, to_index\: :ref:`int`\ ) :ref:`🔗` Moves the bus from index ``index`` to index ``to_index``. @@ -618,11 +738,27 @@ Moves the bus from index ``index`` to index ``to_index``. ---- +.. _class_AudioServer_method_register_stream_as_sample: + +.. rst-class:: classref-method + +|void| **register_stream_as_sample**\ (\ stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Forces the registration of a stream as a sample. + +\ **Note:** Lag spikes may occur when calling this method, especially on single-threaded builds. It is suggested to call this method while loading assets, where the lag spike could be masked, instead of registering the sample right before it needs to be played. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioServer_method_remove_bus: .. rst-class:: classref-method -|void| **remove_bus**\ (\ index\: :ref:`int`\ ) +|void| **remove_bus**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Removes the bus at index ``index``. @@ -634,7 +770,7 @@ Removes the bus at index ``index``. .. rst-class:: classref-method -|void| **remove_bus_effect**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) +|void| **remove_bus_effect**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`\ ) :ref:`🔗` Removes the effect at index ``effect_idx`` from the bus at index ``bus_idx``. @@ -646,7 +782,7 @@ Removes the effect at index ``effect_idx`` from the bus at index ``bus_idx``. .. rst-class:: classref-method -|void| **set_bus_bypass_effects**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **set_bus_bypass_effects**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is bypassing effects. @@ -658,7 +794,7 @@ If ``true``, the bus at index ``bus_idx`` is bypassing effects. .. rst-class:: classref-method -|void| **set_bus_effect_enabled**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) +|void| **set_bus_effect_enabled**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the effect at index ``effect_idx`` on the bus at index ``bus_idx`` is enabled. @@ -670,7 +806,7 @@ If ``true``, the effect at index ``effect_idx`` on the bus at index ``bus_idx`` .. rst-class:: classref-method -|void| **set_bus_layout**\ (\ bus_layout\: :ref:`AudioBusLayout`\ ) +|void| **set_bus_layout**\ (\ bus_layout\: :ref:`AudioBusLayout`\ ) :ref:`🔗` Overwrites the currently used :ref:`AudioBusLayout`. @@ -682,7 +818,7 @@ Overwrites the currently used :ref:`AudioBusLayout`. .. rst-class:: classref-method -|void| **set_bus_mute**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **set_bus_mute**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is muted. @@ -694,7 +830,7 @@ If ``true``, the bus at index ``bus_idx`` is muted. .. rst-class:: classref-method -|void| **set_bus_name**\ (\ bus_idx\: :ref:`int`, name\: :ref:`String`\ ) +|void| **set_bus_name**\ (\ bus_idx\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` Sets the name of the bus at index ``bus_idx`` to ``name``. @@ -706,7 +842,7 @@ Sets the name of the bus at index ``bus_idx`` to ``name``. .. rst-class:: classref-method -|void| **set_bus_send**\ (\ bus_idx\: :ref:`int`, send\: :ref:`StringName`\ ) +|void| **set_bus_send**\ (\ bus_idx\: :ref:`int`, send\: :ref:`StringName`\ ) :ref:`🔗` Connects the output of the bus at ``bus_idx`` to the bus named ``send``. @@ -718,7 +854,7 @@ Connects the output of the bus at ``bus_idx`` to the bus named ``send``. .. rst-class:: classref-method -|void| **set_bus_solo**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **set_bus_solo**\ (\ bus_idx\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, the bus at index ``bus_idx`` is in solo mode. @@ -730,9 +866,23 @@ If ``true``, the bus at index ``bus_idx`` is in solo mode. .. rst-class:: classref-method -|void| **set_bus_volume_db**\ (\ bus_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) +|void| **set_bus_volume_db**\ (\ bus_idx\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` + +Sets the volume in decibels of the bus at index ``bus_idx`` to ``volume_db``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioServer_method_set_bus_volume_linear: + +.. rst-class:: classref-method + +|void| **set_bus_volume_linear**\ (\ bus_idx\: :ref:`int`, volume_linear\: :ref:`float`\ ) :ref:`🔗` + +Sets the volume as a linear value of the bus at index ``bus_idx`` to ``volume_linear``. -Sets the volume of the bus at index ``bus_idx`` to ``volume_db``. +\ **Note:** Using this method is equivalent to calling :ref:`set_bus_volume_db()` with the result of :ref:`@GlobalScope.linear_to_db()` on a value. .. rst-class:: classref-item-separator @@ -742,9 +892,9 @@ Sets the volume of the bus at index ``bus_idx`` to ``volume_db``. .. rst-class:: classref-method -|void| **set_enable_tagging_used_audio_streams**\ (\ enable\: :ref:`bool`\ ) +|void| **set_enable_tagging_used_audio_streams**\ (\ enable\: :ref:`bool`\ ) :ref:`🔗` -If set to ``true``, all instances of :ref:`AudioStreamPlayback` will call :ref:`AudioStreamPlayback._tag_used_streams` every mix step. +If set to ``true``, all instances of :ref:`AudioStreamPlayback` will call :ref:`AudioStreamPlayback._tag_used_streams()` every mix step. \ **Note:** This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews. @@ -756,7 +906,7 @@ If set to ``true``, all instances of :ref:`AudioStreamPlayback`, effect_idx\: :ref:`int`, by_effect_idx\: :ref:`int`\ ) +|void| **swap_bus_effects**\ (\ bus_idx\: :ref:`int`, effect_idx\: :ref:`int`, by_effect_idx\: :ref:`int`\ ) :ref:`🔗` Swaps the position of two effects in bus ``bus_idx``. @@ -768,11 +918,12 @@ Swaps the position of two effects in bus ``bus_idx``. .. rst-class:: classref-method -|void| **unlock**\ (\ ) +|void| **unlock**\ (\ ) :ref:`🔗` Unlocks the audio driver's main loop. (After locking it, you should always unlock it.) .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostream.rst b/classes/class_audiostream.rst index 5f2ed4b47c6..13e2d2d7893 100644 --- a/classes/class_audiostream.rst +++ b/classes/class_audiostream.rst @@ -12,7 +12,7 @@ AudioStream **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioStreamGenerator`, :ref:`AudioStreamMicrophone`, :ref:`AudioStreamMP3`, :ref:`AudioStreamOggVorbis`, :ref:`AudioStreamPolyphonic`, :ref:`AudioStreamRandomizer`, :ref:`AudioStreamWAV` +**Inherited By:** :ref:`AudioStreamGenerator`, :ref:`AudioStreamInteractive`, :ref:`AudioStreamMicrophone`, :ref:`AudioStreamMP3`, :ref:`AudioStreamOggVorbis`, :ref:`AudioStreamPlaylist`, :ref:`AudioStreamPolyphonic`, :ref:`AudioStreamRandomizer`, :ref:`AudioStreamSynchronized`, :ref:`AudioStreamWAV` Base class for audio streams. @@ -30,11 +30,11 @@ Tutorials - :doc:`Audio streams <../tutorials/audio/audio_streams>` -- `Audio Generator Demo `__ +- `Audio Generator Demo `__ -- `Audio Mic Record Demo `__ +- `Audio Microphone Record Demo `__ -- `Audio Spectrum Demo `__ +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -44,6 +44,8 @@ Methods .. table:: :widths: auto + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_get_bar_beats`\ (\ ) |virtual| |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`_get_beat_count`\ (\ ) |virtual| |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ @@ -55,14 +57,24 @@ Methods +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`_get_stream_name`\ (\ ) |virtual| |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`_get_tags`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_has_loop`\ (\ ) |virtual| |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`AudioStreamPlayback` | :ref:`_instantiate_playback`\ (\ ) |virtual| |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_is_monophonic`\ (\ ) |virtual| |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_be_sampled`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioSample` | :ref:`generate_sample`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_length`\ (\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`AudioStreamPlayback` | :ref:`instantiate_playback`\ (\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_meta_stream`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_monophonic`\ (\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------+ @@ -79,7 +91,7 @@ Signals .. rst-class:: classref-signal -**parameter_list_changed**\ (\ ) +**parameter_list_changed**\ (\ ) :ref:`🔗` Signal to be emitted to notify when the parameter list changed. @@ -92,11 +104,23 @@ Signal to be emitted to notify when the parameter list changed. Method Descriptions ------------------- +.. _class_AudioStream_private_method__get_bar_beats: + +.. rst-class:: classref-method + +:ref:`int` **_get_bar_beats**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to return the bar beats of this stream. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStream_private_method__get_beat_count: .. rst-class:: classref-method -:ref:`int` **_get_beat_count**\ (\ ) |virtual| |const| +:ref:`int` **_get_beat_count**\ (\ ) |virtual| |const| :ref:`🔗` Overridable method. Should return the total number of beats of this audio stream. Used by the engine to determine the position of every beat. @@ -110,7 +134,7 @@ Ideally, the returned value should be based off the stream's sample rate (:ref:` .. rst-class:: classref-method -:ref:`float` **_get_bpm**\ (\ ) |virtual| |const| +:ref:`float` **_get_bpm**\ (\ ) |virtual| |const| :ref:`🔗` Overridable method. Should return the tempo of this audio stream, in beats per minute (BPM). Used by the engine to determine the position of every beat. @@ -124,9 +148,9 @@ Ideally, the returned value should be based off the stream's sample rate (:ref:` .. rst-class:: classref-method -:ref:`float` **_get_length**\ (\ ) |virtual| |const| +:ref:`float` **_get_length**\ (\ ) |virtual| |const| :ref:`🔗` -Override this method to customize the returned value of :ref:`get_length`. Should return the length of this audio stream, in seconds. +Override this method to customize the returned value of :ref:`get_length()`. Should return the length of this audio stream, in seconds. .. rst-class:: classref-item-separator @@ -136,9 +160,9 @@ Override this method to customize the returned value of :ref:`get_length`\[:ref:`Dictionary`\] **_get_parameter_list**\ (\ ) |virtual| |const| +:ref:`Array`\[:ref:`Dictionary`\] **_get_parameter_list**\ (\ ) |virtual| |const| :ref:`🔗` -Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see :ref:`Object.get_property_list`). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field. +Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see :ref:`Object.get_property_list()`). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field. .. rst-class:: classref-item-separator @@ -148,7 +172,7 @@ Return the controllable parameters of this stream. This array contains dictionar .. rst-class:: classref-method -:ref:`String` **_get_stream_name**\ (\ ) |virtual| |const| +:ref:`String` **_get_stream_name**\ (\ ) |virtual| |const| :ref:`🔗` Override this method to customize the name assigned to this audio stream. Unused by the engine. @@ -156,13 +180,39 @@ Override this method to customize the name assigned to this audio stream. Unused ---- +.. _class_AudioStream_private_method__get_tags: + +.. rst-class:: classref-method + +:ref:`Dictionary` **_get_tags**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the tags for this audio stream. Should return a :ref:`Dictionary` of strings with the tag as the key and its content as the value. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_private_method__has_loop: + +.. rst-class:: classref-method + +:ref:`bool` **_has_loop**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to return ``true`` if this stream has a loop. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStream_private_method__instantiate_playback: .. rst-class:: classref-method -:ref:`AudioStreamPlayback` **_instantiate_playback**\ (\ ) |virtual| |const| +:ref:`AudioStreamPlayback` **_instantiate_playback**\ (\ ) |virtual| |const| :ref:`🔗` -Override this method to customize the returned value of :ref:`instantiate_playback`. Should returned a new :ref:`AudioStreamPlayback` created when the stream is played (such as by an :ref:`AudioStreamPlayer`).. +Override this method to customize the returned value of :ref:`instantiate_playback()`. Should return a new :ref:`AudioStreamPlayback` created when the stream is played (such as by an :ref:`AudioStreamPlayer`). .. rst-class:: classref-item-separator @@ -172,9 +222,37 @@ Override this method to customize the returned value of :ref:`instantiate_playba .. rst-class:: classref-method -:ref:`bool` **_is_monophonic**\ (\ ) |virtual| |const| +:ref:`bool` **_is_monophonic**\ (\ ) |virtual| |const| :ref:`🔗` + +Override this method to customize the returned value of :ref:`is_monophonic()`. Should return ``true`` if this audio stream only supports one channel. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_can_be_sampled: + +.. rst-class:: classref-method + +:ref:`bool` **can_be_sampled**\ (\ ) |const| :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. -Override this method to customize the returned value of :ref:`is_monophonic`. Should return ``true`` if this audio stream only supports one channel. +Returns if the current **AudioStream** can be used as a sample. Only static streams can be sampled. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_generate_sample: + +.. rst-class:: classref-method + +:ref:`AudioSample` **generate_sample**\ (\ ) |const| :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Generates an :ref:`AudioSample` based on the current stream. .. rst-class:: classref-item-separator @@ -184,9 +262,9 @@ Override this method to customize the returned value of :ref:`is_monophonic` **get_length**\ (\ ) |const| +:ref:`float` **get_length**\ (\ ) |const| :ref:`🔗` -Returns the length of the audio stream in seconds. +Returns the length of the audio stream in seconds. If this stream is an :ref:`AudioStreamRandomizer`, returns the length of the last played stream. If this stream has an indefinite length (such as for :ref:`AudioStreamGenerator` and :ref:`AudioStreamMicrophone`), returns ``0.0``. .. rst-class:: classref-item-separator @@ -196,9 +274,21 @@ Returns the length of the audio stream in seconds. .. rst-class:: classref-method -:ref:`AudioStreamPlayback` **instantiate_playback**\ (\ ) +:ref:`AudioStreamPlayback` **instantiate_playback**\ (\ ) :ref:`🔗` + +Returns a newly created :ref:`AudioStreamPlayback` intended to play this audio stream. Useful for when you want to extend :ref:`_instantiate_playback()` but call :ref:`instantiate_playback()` from an internally held AudioStream subresource. An example of this can be found in the source code for ``AudioStreamRandomPitch::instantiate_playback``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStream_method_is_meta_stream: + +.. rst-class:: classref-method + +:ref:`bool` **is_meta_stream**\ (\ ) |const| :ref:`🔗` -Returns a newly created :ref:`AudioStreamPlayback` intended to play this audio stream. Useful for when you want to extend :ref:`_instantiate_playback` but call :ref:`instantiate_playback` from an internally held AudioStream subresource. An example of this can be found in the source code for ``AudioStreamRandomPitch::instantiate_playback``. +Returns ``true`` if the stream is a collection of other streams, ``false`` otherwise. .. rst-class:: classref-item-separator @@ -208,11 +298,12 @@ Returns a newly created :ref:`AudioStreamPlayback` in .. rst-class:: classref-method -:ref:`bool` **is_monophonic**\ (\ ) |const| +:ref:`bool` **is_monophonic**\ (\ ) |const| :ref:`🔗` Returns ``true`` if this audio stream only supports one channel (*monophony*), or ``false`` if the audio stream supports two or more channels (*polyphony*). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamgenerator.rst b/classes/class_audiostreamgenerator.rst index 813a9764038..6cd9e6adc22 100644 --- a/classes/class_audiostreamgenerator.rst +++ b/classes/class_audiostreamgenerator.rst @@ -31,17 +31,17 @@ Here's a sample on how to use it to generate a sine wave: var playback # Will hold the AudioStreamGeneratorPlayback. @onready var sample_hz = $AudioStreamPlayer.stream.mix_rate var pulse_hz = 440.0 # The frequency of the sound wave. - + var phase = 0.0 + func _ready(): $AudioStreamPlayer.play() playback = $AudioStreamPlayer.get_stream_playback() fill_buffer() - + func fill_buffer(): - var phase = 0.0 var increment = pulse_hz / sample_hz var frames_available = playback.get_frames_available() - + for i in range(frames_available): playback.push_frame(Vector2.ONE * sin(phase * TAU)) phase = fmod(phase + increment, 1.0) @@ -49,11 +49,12 @@ Here's a sample on how to use it to generate a sine wave: .. code-tab:: csharp [Export] public AudioStreamPlayer Player { get; set; } - + private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback. private float _sampleHz; private float _pulseHz = 440.0f; // The frequency of the sound wave. - + private double phase = 0.0; + public override void _Ready() { if (Player.Stream is AudioStreamGenerator generator) // Type as a generator to access MixRate. @@ -64,13 +65,12 @@ Here's a sample on how to use it to generate a sine wave: FillBuffer(); } } - + public void FillBuffer() { - double phase = 0.0; float increment = _pulseHz / _sampleHz; int framesAvailable = _playback.GetFramesAvailable(); - + for (int i = 0; i < framesAvailable; i++) { _playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau)); @@ -91,7 +91,7 @@ See also :ref:`AudioEffectSpectrumAnalyzer` f Tutorials --------- -- `Audio Generator Demo `__ +- `Audio Generator Demo `__ .. rst-class:: classref-reftable-group @@ -101,11 +101,60 @@ Properties .. table:: :widths: auto - +---------------------------+-------------------------------------------------------------------------+-------------+ - | :ref:`float` | :ref:`buffer_length` | ``0.5`` | - +---------------------------+-------------------------------------------------------------------------+-------------+ - | :ref:`float` | :ref:`mix_rate` | ``44100.0`` | - +---------------------------+-------------------------------------------------------------------------+-------------+ + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`buffer_length` | ``0.5`` | + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + | :ref:`float` | :ref:`mix_rate` | ``44100.0`` | + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + | :ref:`AudioStreamGeneratorMixRate` | :ref:`mix_rate_mode` | ``2`` | + +-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioStreamGenerator_AudioStreamGeneratorMixRate: + +.. rst-class:: classref-enumeration + +enum **AudioStreamGeneratorMixRate**: :ref:`🔗` + +.. _class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_OUTPUT** = ``0`` + +Current :ref:`AudioServer` output mixing rate. + +.. _class_AudioStreamGenerator_constant_MIX_RATE_INPUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_INPUT** = ``1`` + +Current :ref:`AudioServer` input mixing rate. + +.. _class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_CUSTOM** = ``2`` + +Custom mixing rate, specified by :ref:`mix_rate`. + +.. _class_AudioStreamGenerator_constant_MIX_RATE_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`AudioStreamGeneratorMixRate` **MIX_RATE_MAX** = ``3`` + +Maximum value for the mixing rate mode enum. .. rst-class:: classref-section-separator @@ -120,7 +169,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **buffer_length** = ``0.5`` +:ref:`float` **buffer_length** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -137,7 +186,7 @@ The length of the buffer to generate (in seconds). Lower values result in less l .. rst-class:: classref-property -:ref:`float` **mix_rate** = ``44100.0`` +:ref:`float` **mix_rate** = ``44100.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -150,7 +199,29 @@ In games, common sample rates in use are ``11025``, ``16000``, ``22050``, ``3200 According to the `Nyquist-Shannon sampling theorem `__, there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are generating lower-pitched sounds such as voices, lower sample rates such as ``32000`` or ``22050`` may be usable with no loss in quality. +\ **Note:** **AudioStreamGenerator** is not automatically resampling input data, to produce expected result :ref:`mix_rate_mode` should match the sampling rate of input data. + +\ **Note:** If you are using :ref:`AudioEffectCapture` as the source of your data, set :ref:`mix_rate_mode` to :ref:`MIX_RATE_INPUT` or :ref:`MIX_RATE_OUTPUT` to automatically match current :ref:`AudioServer` mixing rate. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamGenerator_property_mix_rate_mode: + +.. rst-class:: classref-property + +:ref:`AudioStreamGeneratorMixRate` **mix_rate_mode** = ``2`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mix_rate_mode**\ (\ value\: :ref:`AudioStreamGeneratorMixRate`\ ) +- :ref:`AudioStreamGeneratorMixRate` **get_mix_rate_mode**\ (\ ) + +Mixing rate mode. If set to :ref:`MIX_RATE_CUSTOM`, :ref:`mix_rate` is used, otherwise current :ref:`AudioServer` mixing rate is used. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamgeneratorplayback.rst b/classes/class_audiostreamgeneratorplayback.rst index 809e157ce29..17314378a8a 100644 --- a/classes/class_audiostreamgeneratorplayback.rst +++ b/classes/class_audiostreamgeneratorplayback.rst @@ -26,7 +26,7 @@ This class is meant to be used with :ref:`AudioStreamGenerator`__ +- `Audio Generator Demo `__ - `Godot 3.2 will get new audio features `__ @@ -65,7 +65,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`bool` **can_push_buffer**\ (\ amount\: :ref:`int`\ ) |const| +:ref:`bool` **can_push_buffer**\ (\ amount\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if a buffer of the size ``amount`` can be pushed to the audio sample data buffer without overflowing it, ``false`` otherwise. @@ -77,7 +77,7 @@ Returns ``true`` if a buffer of the size ``amount`` can be pushed to the audio s .. rst-class:: classref-method -|void| **clear_buffer**\ (\ ) +|void| **clear_buffer**\ (\ ) :ref:`🔗` Clears the audio sample data buffer. @@ -89,7 +89,7 @@ Clears the audio sample data buffer. .. rst-class:: classref-method -:ref:`int` **get_frames_available**\ (\ ) |const| +:ref:`int` **get_frames_available**\ (\ ) |const| :ref:`🔗` Returns the number of frames that can be pushed to the audio sample data buffer without overflowing it. If the result is ``0``, the buffer is full. @@ -101,7 +101,7 @@ Returns the number of frames that can be pushed to the audio sample data buffer .. rst-class:: classref-method -:ref:`int` **get_skips**\ (\ ) |const| +:ref:`int` **get_skips**\ (\ ) |const| :ref:`🔗` Returns the number of times the playback skipped due to a buffer underrun in the audio sample data. This value is reset at the start of the playback. @@ -113,9 +113,9 @@ Returns the number of times the playback skipped due to a buffer underrun in the .. rst-class:: classref-method -:ref:`bool` **push_buffer**\ (\ frames\: :ref:`PackedVector2Array`\ ) +:ref:`bool` **push_buffer**\ (\ frames\: :ref:`PackedVector2Array`\ ) :ref:`🔗` -Pushes several audio data frames to the buffer. This is usually more efficient than :ref:`push_frame` in C# and compiled languages via GDExtension, but :ref:`push_buffer` may be *less* efficient in GDScript. +Pushes several audio data frames to the buffer. This is usually more efficient than :ref:`push_frame()` in C# and compiled languages via GDExtension, but :ref:`push_buffer()` may be *less* efficient in GDScript. .. rst-class:: classref-item-separator @@ -125,11 +125,12 @@ Pushes several audio data frames to the buffer. This is usually more efficient t .. rst-class:: classref-method -:ref:`bool` **push_frame**\ (\ frame\: :ref:`Vector2`\ ) +:ref:`bool` **push_frame**\ (\ frame\: :ref:`Vector2`\ ) :ref:`🔗` -Pushes a single audio data frame to the buffer. This is usually less efficient than :ref:`push_buffer` in C# and compiled languages via GDExtension, but :ref:`push_frame` may be *more* efficient in GDScript. +Pushes a single audio data frame to the buffer. This is usually less efficient than :ref:`push_buffer()` in C# and compiled languages via GDExtension, but :ref:`push_frame()` may be *more* efficient in GDScript. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreaminteractive.rst b/classes/class_audiostreaminteractive.rst new file mode 100644 index 00000000000..371782ef65f --- /dev/null +++ b/classes/class_audiostreaminteractive.rst @@ -0,0 +1,556 @@ +: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/modules/interactive_music/doc_classes/AudioStreamInteractive.xml. + +.. _class_AudioStreamInteractive: + +AudioStreamInteractive +====================== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Audio stream that can playback music interactively, combining clips and a transition table. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This is an audio stream that can playback music interactively, combining clips and a transition table. Clips must be added first, and then the transition rules via the :ref:`add_transition()`. Additionally, this stream exports a property parameter to control the playback via :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`. + +The way this is used is by filling a number of clips, then configuring the transition table. From there, clips are selected for playback and the music will smoothly go from the current to the new one while using the corresponding transition rule defined in the transition table. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+-------------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`clip_count` | ``0`` | + +-----------------------+-------------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`initial_clip` | ``0`` | + +-----------------------+-------------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_transition`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`, from_time\: :ref:`TransitionFromTime`, to_time\: :ref:`TransitionToTime`, fade_mode\: :ref:`FadeMode`, fade_beats\: :ref:`float`, use_filler_clip\: :ref:`bool` = false, filler_clip\: :ref:`int` = -1, hold_previous\: :ref:`bool` = false\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`erase_transition`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AutoAdvanceMode` | :ref:`get_clip_auto_advance`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_clip_auto_advance_next_clip`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_clip_name`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_clip_stream`\ (\ clip_index\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_transition_fade_beats`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FadeMode` | :ref:`get_transition_fade_mode`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_transition_filler_clip`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`TransitionFromTime` | :ref:`get_transition_from_time`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_transition_list`\ (\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`TransitionToTime` | :ref:`get_transition_to_time`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_transition`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_transition_holding_previous`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_transition_using_filler_clip`\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_auto_advance`\ (\ clip_index\: :ref:`int`, mode\: :ref:`AutoAdvanceMode`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_auto_advance_next_clip`\ (\ clip_index\: :ref:`int`, auto_advance_next_clip\: :ref:`int`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_name`\ (\ clip_index\: :ref:`int`, name\: :ref:`StringName`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_clip_stream`\ (\ clip_index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) | + +---------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_AudioStreamInteractive_TransitionFromTime: + +.. rst-class:: classref-enumeration + +enum **TransitionFromTime**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_IMMEDIATE: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_IMMEDIATE** = ``0`` + +Start transition as soon as possible, don't wait for any specific time position. + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_NEXT_BEAT: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_NEXT_BEAT** = ``1`` + +Transition when the clip playback position reaches the next beat. + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_NEXT_BAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_NEXT_BAR** = ``2`` + +Transition when the clip playback position reaches the next bar. + +.. _class_AudioStreamInteractive_constant_TRANSITION_FROM_TIME_END: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionFromTime` **TRANSITION_FROM_TIME_END** = ``3`` + +Transition when the current clip finished playing. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamInteractive_TransitionToTime: + +.. rst-class:: classref-enumeration + +enum **TransitionToTime**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_TRANSITION_TO_TIME_SAME_POSITION: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionToTime` **TRANSITION_TO_TIME_SAME_POSITION** = ``0`` + +Transition to the same position in the destination clip. This is useful when both clips have exactly the same length and the music should fade between them. + +.. _class_AudioStreamInteractive_constant_TRANSITION_TO_TIME_START: + +.. rst-class:: classref-enumeration-constant + +:ref:`TransitionToTime` **TRANSITION_TO_TIME_START** = ``1`` + +Transition to the start of the destination clip. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamInteractive_FadeMode: + +.. rst-class:: classref-enumeration + +enum **FadeMode**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_FADE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_DISABLED** = ``0`` + +Do not use fade for the transition. This is useful when transitioning from a clip-end to clip-beginning, and each clip has their begin/end. + +.. _class_AudioStreamInteractive_constant_FADE_IN: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_IN** = ``1`` + +Use a fade-in in the next clip, let the current clip finish. + +.. _class_AudioStreamInteractive_constant_FADE_OUT: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_OUT** = ``2`` + +Use a fade-out in the current clip, the next clip will start by itself. + +.. _class_AudioStreamInteractive_constant_FADE_CROSS: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_CROSS** = ``3`` + +Use a cross-fade between clips. + +.. _class_AudioStreamInteractive_constant_FADE_AUTOMATIC: + +.. rst-class:: classref-enumeration-constant + +:ref:`FadeMode` **FADE_AUTOMATIC** = ``4`` + +Use automatic fade logic depending on the transition from/to. It is recommended to use this by default. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_AudioStreamInteractive_AutoAdvanceMode: + +.. rst-class:: classref-enumeration + +enum **AutoAdvanceMode**: :ref:`🔗` + +.. _class_AudioStreamInteractive_constant_AUTO_ADVANCE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AutoAdvanceMode` **AUTO_ADVANCE_DISABLED** = ``0`` + +Disable auto-advance (default). + +.. _class_AudioStreamInteractive_constant_AUTO_ADVANCE_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`AutoAdvanceMode` **AUTO_ADVANCE_ENABLED** = ``1`` + +Enable auto-advance, a clip must be specified. + +.. _class_AudioStreamInteractive_constant_AUTO_ADVANCE_RETURN_TO_HOLD: + +.. rst-class:: classref-enumeration-constant + +:ref:`AutoAdvanceMode` **AUTO_ADVANCE_RETURN_TO_HOLD** = ``2`` + +Enable auto-advance, but instead of specifying a clip, the playback will return to hold (see :ref:`add_transition()`). + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamInteractive_constant_CLIP_ANY: + +.. rst-class:: classref-constant + +**CLIP_ANY** = ``-1`` :ref:`🔗` + +This constant describes that any clip is valid for a specific transition as either source or destination. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamInteractive_property_clip_count: + +.. rst-class:: classref-property + +:ref:`int` **clip_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_clip_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_clip_count**\ (\ ) + +Amount of clips contained in this interactive player. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_property_initial_clip: + +.. rst-class:: classref-property + +:ref:`int` **initial_clip** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_initial_clip**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_initial_clip**\ (\ ) + +Index of the initial clip, which will be played first when this stream is played. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamInteractive_method_add_transition: + +.. rst-class:: classref-method + +|void| **add_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`, from_time\: :ref:`TransitionFromTime`, to_time\: :ref:`TransitionToTime`, fade_mode\: :ref:`FadeMode`, fade_beats\: :ref:`float`, use_filler_clip\: :ref:`bool` = false, filler_clip\: :ref:`int` = -1, hold_previous\: :ref:`bool` = false\ ) :ref:`🔗` + +Add a transition between two clips. Provide the indices of the source and destination clips, or use the :ref:`CLIP_ANY` constant to indicate that transition happens to/from any clip to this one. + +\* ``from_time`` indicates the moment in the current clip the transition will begin after triggered. + +\* ``to_time`` indicates the time in the next clip that the playback will start from. + +\* ``fade_mode`` indicates how the fade will happen between clips. If unsure, just use :ref:`FADE_AUTOMATIC` which uses the most common type of fade for each situation. + +\* ``fade_beats`` indicates how many beats the fade will take. Using decimals is allowed. + +\* ``use_filler_clip`` indicates that there will be a filler clip used between the source and destination clips. + +\* ``filler_clip`` the index of the filler clip. + +\* If ``hold_previous`` is used, then this clip will be remembered. This can be used together with :ref:`AUTO_ADVANCE_RETURN_TO_HOLD` to return to this clip after another is done playing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_erase_transition: + +.. rst-class:: classref-method + +|void| **erase_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) :ref:`🔗` + +Erase a transition by providing ``from_clip`` and ``to_clip`` clip indices. :ref:`CLIP_ANY` can be used for either argument or both. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_auto_advance: + +.. rst-class:: classref-method + +:ref:`AutoAdvanceMode` **get_clip_auto_advance**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return whether a clip has auto-advance enabled. See :ref:`set_clip_auto_advance()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_auto_advance_next_clip: + +.. rst-class:: classref-method + +:ref:`int` **get_clip_auto_advance_next_clip**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the clip towards which the clip referenced by ``clip_index`` will auto-advance to. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_name: + +.. rst-class:: classref-method + +:ref:`StringName` **get_clip_name**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the name of a clip. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_clip_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_clip_stream**\ (\ clip_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the :ref:`AudioStream` associated with a clip. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_fade_beats: + +.. rst-class:: classref-method + +:ref:`float` **get_transition_fade_beats**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the time (in beats) for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_fade_mode: + +.. rst-class:: classref-method + +:ref:`FadeMode` **get_transition_fade_mode**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the mode for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_filler_clip: + +.. rst-class:: classref-method + +:ref:`int` **get_transition_filler_clip**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the filler clip for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_from_time: + +.. rst-class:: classref-method + +:ref:`TransitionFromTime` **get_transition_from_time**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the source time position for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_list: + +.. rst-class:: classref-method + +:ref:`PackedInt32Array` **get_transition_list**\ (\ ) |const| :ref:`🔗` + +Return the list of transitions (from, to interleaved). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_get_transition_to_time: + +.. rst-class:: classref-method + +:ref:`TransitionToTime` **get_transition_to_time**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return the destination time position for a transition (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_has_transition: + +.. rst-class:: classref-method + +:ref:`bool` **has_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if a given transition exists (was added via :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_is_transition_holding_previous: + +.. rst-class:: classref-method + +:ref:`bool` **is_transition_holding_previous**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return whether a transition uses the *hold previous* functionality (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_is_transition_using_filler_clip: + +.. rst-class:: classref-method + +:ref:`bool` **is_transition_using_filler_clip**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`🔗` + +Return whether a transition uses the *filler clip* functionality (see :ref:`add_transition()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_auto_advance: + +.. rst-class:: classref-method + +|void| **set_clip_auto_advance**\ (\ clip_index\: :ref:`int`, mode\: :ref:`AutoAdvanceMode`\ ) :ref:`🔗` + +Set whether a clip will auto-advance by changing the auto-advance mode. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_auto_advance_next_clip: + +.. rst-class:: classref-method + +|void| **set_clip_auto_advance_next_clip**\ (\ clip_index\: :ref:`int`, auto_advance_next_clip\: :ref:`int`\ ) :ref:`🔗` + +Set the index of the next clip towards which this clip will auto advance to when finished. If the clip being played loops, then auto-advance will be ignored. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_name: + +.. rst-class:: classref-method + +|void| **set_clip_name**\ (\ clip_index\: :ref:`int`, name\: :ref:`StringName`\ ) :ref:`🔗` + +Set the name of the current clip (for easier identification). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamInteractive_method_set_clip_stream: + +.. rst-class:: classref-method + +|void| **set_clip_stream**\ (\ clip_index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Set the :ref:`AudioStream` associated with the current clip. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreammicrophone.rst b/classes/class_audiostreammicrophone.rst index c90316ec693..8c6a4c0408c 100644 --- a/classes/class_audiostreammicrophone.rst +++ b/classes/class_audiostreammicrophone.rst @@ -33,6 +33,7 @@ Tutorials - `Audio Mic Record Demo `__ .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreammp3.rst b/classes/class_audiostreammp3.rst index ee031252d79..a7a016823b9 100644 --- a/classes/class_audiostreammp3.rst +++ b/classes/class_audiostreammp3.rst @@ -21,6 +21,8 @@ Description MP3 audio stream driver. See :ref:`data` if you want to load an MP3 file at run-time. +\ **Note:** This class can optionally support legacy MP1 and MP2 formats, provided that the engine is compiled with the ``minimp3_extra_formats=yes`` SCons option. These extra formats are not enabled by default. + .. rst-class:: classref-reftable-group Properties @@ -43,6 +45,20 @@ Properties | :ref:`float` | :ref:`loop_offset` | ``0.0`` | +-----------------------------------------------+---------------------------------------------------------------+-----------------------+ +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamMP3` | :ref:`load_from_buffer`\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| | + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamMP3` | :ref:`load_from_file`\ (\ path\: :ref:`String`\ ) |static| | + +---------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + .. rst-class:: classref-section-separator ---- @@ -56,7 +72,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **bar_beats** = ``4`` +:ref:`int` **bar_beats** = ``4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -75,7 +91,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **beat_count** = ``0`` +:ref:`int` **beat_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -94,7 +110,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **bpm** = ``0.0`` +:ref:`float` **bpm** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -113,7 +129,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`PackedByteArray` **data** = ``PackedByteArray()`` +:ref:`PackedByteArray` **data** = ``PackedByteArray()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -147,6 +163,8 @@ You can load a file without having to import it beforehand using the code snippe +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedByteArray` for more details. + .. rst-class:: classref-item-separator ---- @@ -155,7 +173,7 @@ You can load a file without having to import it beforehand using the code snippe .. rst-class:: classref-property -:ref:`bool` **loop** = ``false`` +:ref:`bool` **loop** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -172,7 +190,7 @@ If ``true``, the stream will automatically loop when it reaches the end. .. rst-class:: classref-property -:ref:`float` **loop_offset** = ``0.0`` +:ref:`float` **loop_offset** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -181,7 +199,37 @@ If ``true``, the stream will automatically loop when it reaches the end. Time in seconds at which the stream starts after being looped. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamMP3_method_load_from_buffer: + +.. rst-class:: classref-method + +:ref:`AudioStreamMP3` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamMP3** instance from the given buffer. The buffer must contain MP3 data. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamMP3_method_load_from_file: + +.. rst-class:: classref-method + +:ref:`AudioStreamMP3` **load_from_file**\ (\ path\: :ref:`String`\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamMP3** instance from the given file path. The file must be in MP3 format. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamoggvorbis.rst b/classes/class_audiostreamoggvorbis.rst index 08ae8ab23a1..a2875051489 100644 --- a/classes/class_audiostreamoggvorbis.rst +++ b/classes/class_audiostreamoggvorbis.rst @@ -49,6 +49,8 @@ Properties +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ | :ref:`OggPacketSequence` | :ref:`packet_sequence` | | +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ + | :ref:`Dictionary` | :ref:`tags` | ``{}`` | + +---------------------------------------------------+-----------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group @@ -58,11 +60,11 @@ Methods .. table:: :widths: auto - +---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`AudioStreamOggVorbis` | :ref:`load_from_buffer`\ (\ buffer\: :ref:`PackedByteArray`\ ) |static| | - +---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`AudioStreamOggVorbis` | :ref:`load_from_file`\ (\ path\: :ref:`String`\ ) |static| | - +---------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+ + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamOggVorbis` | :ref:`load_from_buffer`\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamOggVorbis` | :ref:`load_from_file`\ (\ path\: :ref:`String`\ ) |static| | + +---------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -77,7 +79,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **bar_beats** = ``4`` +:ref:`int` **bar_beats** = ``4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -96,7 +98,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **beat_count** = ``0`` +:ref:`int` **beat_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -115,7 +117,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **bpm** = ``0.0`` +:ref:`float` **bpm** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -134,7 +136,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **loop** = ``false`` +:ref:`bool` **loop** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -151,7 +153,7 @@ If ``true``, the audio will play again from the specified :ref:`loop_offset` **loop_offset** = ``0.0`` +:ref:`float` **loop_offset** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -168,7 +170,7 @@ Time in seconds at which the stream starts after being looped. .. rst-class:: classref-property -:ref:`OggPacketSequence` **packet_sequence** +:ref:`OggPacketSequence` **packet_sequence** :ref:`🔗` .. rst-class:: classref-property-setget @@ -177,6 +179,27 @@ Time in seconds at which the stream starts after being looped. Contains the raw Ogg data for this stream. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamOggVorbis_property_tags: + +.. rst-class:: classref-property + +:ref:`Dictionary` **tags** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tags**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_tags**\ (\ ) + +Contains user-defined tags if found in the Ogg Vorbis data. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date`` (``date`` does not have a standard date format). + +\ **Note:** No tag is *guaranteed* to be present in every file, so make sure to account for the keys not always existing. + .. rst-class:: classref-section-separator ---- @@ -190,9 +213,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`AudioStreamOggVorbis` **load_from_buffer**\ (\ buffer\: :ref:`PackedByteArray`\ ) |static| +:ref:`AudioStreamOggVorbis` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray`\ ) |static| :ref:`🔗` -Creates a new AudioStreamOggVorbis instance from the given buffer. The buffer must contain Ogg Vorbis data. +Creates a new **AudioStreamOggVorbis** instance from the given buffer. The buffer must contain Ogg Vorbis data. .. rst-class:: classref-item-separator @@ -202,11 +225,12 @@ Creates a new AudioStreamOggVorbis instance from the given buffer. The buffer mu .. rst-class:: classref-method -:ref:`AudioStreamOggVorbis` **load_from_file**\ (\ path\: :ref:`String`\ ) |static| +:ref:`AudioStreamOggVorbis` **load_from_file**\ (\ path\: :ref:`String`\ ) |static| :ref:`🔗` -Creates a new AudioStreamOggVorbis instance from the given file path. The file must be in Ogg Vorbis format. +Creates a new **AudioStreamOggVorbis** instance from the given file path. The file must be in Ogg Vorbis format. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplayback.rst b/classes/class_audiostreamplayback.rst index ebde6a874bd..c368a962909 100644 --- a/classes/class_audiostreamplayback.rst +++ b/classes/class_audiostreamplayback.rst @@ -12,7 +12,7 @@ AudioStreamPlayback **Inherits:** :ref:`RefCounted` **<** :ref:`Object` -**Inherited By:** :ref:`AudioStreamPlaybackPolyphonic`, :ref:`AudioStreamPlaybackResampled` +**Inherited By:** :ref:`AudioStreamPlaybackInteractive`, :ref:`AudioStreamPlaybackPlaylist`, :ref:`AudioStreamPlaybackPolyphonic`, :ref:`AudioStreamPlaybackResampled`, :ref:`AudioStreamPlaybackSynchronized` Meta class for playing back audio. @@ -28,7 +28,7 @@ Can play, loop, pause a scroll through audio. See :ref:`AudioStream`__ +- `Audio Generator Demo `__ .. rst-class:: classref-reftable-group @@ -38,27 +38,45 @@ Methods .. table:: :widths: auto - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`_get_loop_count`\ (\ ) |virtual| |const| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`_get_parameter`\ (\ name\: :ref:`StringName`\ ) |virtual| |const| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_get_playback_position`\ (\ ) |virtual| |const| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`_is_playing`\ (\ ) |virtual| |const| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`_mix`\ (\ buffer\: ``AudioFrame*``, rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) |virtual| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_seek`\ (\ position\: :ref:`float`\ ) |virtual| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_set_parameter`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) |virtual| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_start`\ (\ from_pos\: :ref:`float`\ ) |virtual| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_stop`\ (\ ) |virtual| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_tag_used_streams`\ (\ ) |virtual| | - +-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_get_loop_count`\ (\ ) |virtual| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`_get_parameter`\ (\ name\: :ref:`StringName`\ ) |virtual| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_get_playback_position`\ (\ ) |virtual| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_is_playing`\ (\ ) |virtual| |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_mix`\ (\ buffer\: ``AudioFrame*``, rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) |virtual| |required| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_seek`\ (\ position\: :ref:`float`\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_set_parameter`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_start`\ (\ from_pos\: :ref:`float`\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_stop`\ (\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_tag_used_streams`\ (\ ) |virtual| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_loop_count`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playback_position`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioSamplePlayback` | :ref:`get_sample_playback`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`mix_audio`\ (\ rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ time\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_sample_playback`\ (\ playback_sample\: :ref:`AudioSamplePlayback`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`start`\ (\ from_pos\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -73,7 +91,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`int` **_get_loop_count**\ (\ ) |virtual| |const| +:ref:`int` **_get_loop_count**\ (\ ) |virtual| |const| :ref:`🔗` Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return ``0``. @@ -85,9 +103,9 @@ Overridable method. Should return how many times this audio stream has looped. M .. rst-class:: classref-method -:ref:`Variant` **_get_parameter**\ (\ name\: :ref:`StringName`\ ) |virtual| |const| +:ref:`Variant` **_get_parameter**\ (\ name\: :ref:`StringName`\ ) |virtual| |const| :ref:`🔗` -Return the current value of a playback parameter by name (see :ref:`AudioStream._get_parameter_list`). +Return the current value of a playback parameter by name (see :ref:`AudioStream._get_parameter_list()`). .. rst-class:: classref-item-separator @@ -97,7 +115,7 @@ Return the current value of a playback parameter by name (see :ref:`AudioStream. .. rst-class:: classref-method -:ref:`float` **_get_playback_position**\ (\ ) |virtual| |const| +:ref:`float` **_get_playback_position**\ (\ ) |virtual| |const| :ref:`🔗` Overridable method. Should return the current progress along the audio stream, in seconds. @@ -109,7 +127,7 @@ Overridable method. Should return the current progress along the audio stream, i .. rst-class:: classref-method -:ref:`bool` **_is_playing**\ (\ ) |virtual| |const| +:ref:`bool` **_is_playing**\ (\ ) |virtual| |const| :ref:`🔗` Overridable method. Should return ``true`` if this playback is active and playing its audio stream. @@ -121,7 +139,7 @@ Overridable method. Should return ``true`` if this playback is active and playin .. rst-class:: classref-method -:ref:`int` **_mix**\ (\ buffer\: ``AudioFrame*``, rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) |virtual| +:ref:`int` **_mix**\ (\ buffer\: ``AudioFrame*``, rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) |virtual| |required| :ref:`🔗` Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active. @@ -135,9 +153,9 @@ Override this method to customize how the audio stream is mixed. This method is .. rst-class:: classref-method -|void| **_seek**\ (\ position\: :ref:`float`\ ) |virtual| +|void| **_seek**\ (\ position\: :ref:`float`\ ) |virtual| :ref:`🔗` -Override this method to customize what happens when seeking this audio stream at the given ``position``, such as by calling :ref:`AudioStreamPlayer.seek`. +Override this method to customize what happens when seeking this audio stream at the given ``position``, such as by calling :ref:`AudioStreamPlayer.seek()`. .. rst-class:: classref-item-separator @@ -147,9 +165,9 @@ Override this method to customize what happens when seeking this audio stream at .. rst-class:: classref-method -|void| **_set_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) |virtual| +|void| **_set_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) |virtual| :ref:`🔗` -Set the current value of a playback parameter by name (see :ref:`AudioStream._get_parameter_list`). +Set the current value of a playback parameter by name (see :ref:`AudioStream._get_parameter_list()`). .. rst-class:: classref-item-separator @@ -159,9 +177,9 @@ Set the current value of a playback parameter by name (see :ref:`AudioStream._ge .. rst-class:: classref-method -|void| **_start**\ (\ from_pos\: :ref:`float`\ ) |virtual| +|void| **_start**\ (\ from_pos\: :ref:`float`\ ) |virtual| :ref:`🔗` -Override this method to customize what happens when the playback starts at the given position, such as by calling :ref:`AudioStreamPlayer.play`. +Override this method to customize what happens when the playback starts at the given position, such as by calling :ref:`AudioStreamPlayer.play()`. .. rst-class:: classref-item-separator @@ -171,9 +189,9 @@ Override this method to customize what happens when the playback starts at the g .. rst-class:: classref-method -|void| **_stop**\ (\ ) |virtual| +|void| **_stop**\ (\ ) |virtual| :ref:`🔗` -Override this method to customize what happens when the playback is stopped, such as by calling :ref:`AudioStreamPlayer.stop`. +Override this method to customize what happens when the playback is stopped, such as by calling :ref:`AudioStreamPlayer.stop()`. .. rst-class:: classref-item-separator @@ -183,11 +201,128 @@ Override this method to customize what happens when the playback is stopped, suc .. rst-class:: classref-method -|void| **_tag_used_streams**\ (\ ) |virtual| +|void| **_tag_used_streams**\ (\ ) |virtual| :ref:`🔗` -Overridable method. Called whenever the audio stream is mixed if the playback is active and :ref:`AudioServer.set_enable_tagging_used_audio_streams` has been set to ``true``. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview. +Overridable method. Called whenever the audio stream is mixed if the playback is active and :ref:`AudioServer.set_enable_tagging_used_audio_streams()` has been set to ``true``. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_loop_count: + +.. rst-class:: classref-method + +:ref:`int` **get_loop_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of times the stream has looped. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_playback_position: + +.. rst-class:: classref-method + +:ref:`float` **get_playback_position**\ (\ ) |const| :ref:`🔗` + +Returns the current position in the stream, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_sample_playback: + +.. rst-class:: classref-method + +:ref:`AudioSamplePlayback` **get_sample_playback**\ (\ ) |const| :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Returns the :ref:`AudioSamplePlayback` associated with this **AudioStreamPlayback** for playing back the audio sample of this stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_is_playing: + +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the stream is playing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_mix_audio: + +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **mix_audio**\ (\ rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) :ref:`🔗` + +Mixes up to ``frames`` of audio from the stream from the current position, at a rate of ``rate_scale``, advancing the stream. + +Returns a :ref:`PackedVector2Array` where each element holds the left and right channel volume levels of each frame. + +\ **Note:** Can return fewer frames than requested, make sure to use the size of the return value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_seek: + +.. rst-class:: classref-method + +|void| **seek**\ (\ time\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Seeks the stream at the given ``time``, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_set_sample_playback: + +.. rst-class:: classref-method + +|void| **set_sample_playback**\ (\ playback_sample\: :ref:`AudioSamplePlayback`\ ) :ref:`🔗` + +**Experimental:** This method may be changed or removed in future versions. + +Associates :ref:`AudioSamplePlayback` to this **AudioStreamPlayback** for playing back the audio sample of this stream. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_start: + +.. rst-class:: classref-method + +|void| **start**\ (\ from_pos\: :ref:`float` = 0.0\ ) :ref:`🔗` + +Starts the stream from the given ``from_pos``, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_stop: + +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`🔗` + +Stops the stream. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplaybackinteractive.rst b/classes/class_audiostreamplaybackinteractive.rst new file mode 100644 index 00000000000..c80a3e690b6 --- /dev/null +++ b/classes/class_audiostreamplaybackinteractive.rst @@ -0,0 +1,100 @@ +: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/modules/interactive_music/doc_classes/AudioStreamPlaybackInteractive.xml. + +.. _class_AudioStreamPlaybackInteractive: + +AudioStreamPlaybackInteractive +============================== + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +Playback component of :ref:`AudioStreamInteractive`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Playback component of :ref:`AudioStreamInteractive`. Contains functions to change the currently played clip. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_current_clip_index`\ (\ ) |const| | + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`switch_to_clip`\ (\ clip_index\: :ref:`int`\ ) | + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`switch_to_clip_by_name`\ (\ clip_name\: :ref:`StringName`\ ) | + +-----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlaybackInteractive_method_get_current_clip_index: + +.. rst-class:: classref-method + +:ref:`int` **get_current_clip_index**\ (\ ) |const| :ref:`🔗` + +Return the index of the currently playing clip. You can use this to get the name of the currently playing clip with :ref:`AudioStreamInteractive.get_clip_name()`. + +\ **Example:** Get the currently playing clip name from inside an :ref:`AudioStreamPlayer` node. + + +.. tabs:: + + .. code-tab:: gdscript + + var playing_clip_name = stream.get_clip_name(get_stream_playback().get_current_clip_index()) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackInteractive_method_switch_to_clip: + +.. rst-class:: classref-method + +|void| **switch_to_clip**\ (\ clip_index\: :ref:`int`\ ) :ref:`🔗` + +Switch to a clip (by index). + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaybackInteractive_method_switch_to_clip_by_name: + +.. rst-class:: classref-method + +|void| **switch_to_clip_by_name**\ (\ clip_name\: :ref:`StringName`\ ) :ref:`🔗` + +Switch to a clip (by name). + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackoggvorbis.rst b/classes/class_audiostreamplaybackoggvorbis.rst index dc0f2c757a3..e89c61e1896 100644 --- a/classes/class_audiostreamplaybackoggvorbis.rst +++ b/classes/class_audiostreamplaybackoggvorbis.rst @@ -17,6 +17,7 @@ AudioStreamPlaybackOggVorbis There is currently no description for this class. Please help us by :ref:`contributing one `! .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplaybackplaylist.rst b/classes/class_audiostreamplaybackplaylist.rst new file mode 100644 index 00000000000..dbc521cd265 --- /dev/null +++ b/classes/class_audiostreamplaybackplaylist.rst @@ -0,0 +1,25 @@ +: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/modules/interactive_music/doc_classes/AudioStreamPlaybackPlaylist.xml. + +.. _class_AudioStreamPlaybackPlaylist: + +AudioStreamPlaybackPlaylist +=========================== + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +Playback class used for :ref:`AudioStreamPlaylist`. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplaybackpolyphonic.rst b/classes/class_audiostreamplaybackpolyphonic.rst index 293103460a2..6575a1a7727 100644 --- a/classes/class_audiostreamplaybackpolyphonic.rst +++ b/classes/class_audiostreamplaybackpolyphonic.rst @@ -19,7 +19,7 @@ Playback instance for :ref:`AudioStreamPolyphonic`. Description ----------- -Playback instance for :ref:`AudioStreamPolyphonic`. After setting the ``stream`` property of :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`, the playback instance can be obtained by calling :ref:`AudioStreamPlayer.get_stream_playback`, :ref:`AudioStreamPlayer2D.get_stream_playback` or :ref:`AudioStreamPlayer3D.get_stream_playback` methods. +Playback instance for :ref:`AudioStreamPolyphonic`. After setting the ``stream`` property of :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`, the playback instance can be obtained by calling :ref:`AudioStreamPlayer.get_stream_playback()`, :ref:`AudioStreamPlayer2D.get_stream_playback()` or :ref:`AudioStreamPlayer3D.get_stream_playback()` methods. .. rst-class:: classref-reftable-group @@ -29,17 +29,17 @@ Methods .. table:: :widths: auto - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_stream_playing`\ (\ stream\: :ref:`int`\ ) |const| | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`play_stream`\ (\ stream\: :ref:`AudioStream`, from_offset\: :ref:`float` = 0, volume_db\: :ref:`float` = 0, pitch_scale\: :ref:`float` = 1.0\ ) | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_stream_pitch_scale`\ (\ stream\: :ref:`int`, pitch_scale\: :ref:`float`\ ) | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_stream_volume`\ (\ stream\: :ref:`int`, volume_db\: :ref:`float`\ ) | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`stop_stream`\ (\ stream\: :ref:`int`\ ) | - +-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_stream_playing`\ (\ stream\: :ref:`int`\ ) |const| | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`play_stream`\ (\ stream\: :ref:`AudioStream`, from_offset\: :ref:`float` = 0, volume_db\: :ref:`float` = 0, pitch_scale\: :ref:`float` = 1.0, playback_type\: :ref:`PlaybackType` = 0, bus\: :ref:`StringName` = &"Master"\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_stream_pitch_scale`\ (\ stream\: :ref:`int`, pitch_scale\: :ref:`float`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_stream_volume`\ (\ stream\: :ref:`int`, volume_db\: :ref:`float`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop_stream`\ (\ stream\: :ref:`int`\ ) | + +-------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -54,9 +54,9 @@ Constants .. rst-class:: classref-constant -**INVALID_ID** = ``-1`` +**INVALID_ID** = ``-1`` :ref:`🔗` -Returned by :ref:`play_stream` in case it could not allocate a stream for playback. +Returned by :ref:`play_stream()` in case it could not allocate a stream for playback. .. rst-class:: classref-section-separator @@ -71,9 +71,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`bool` **is_stream_playing**\ (\ stream\: :ref:`int`\ ) |const| +:ref:`bool` **is_stream_playing**\ (\ stream\: :ref:`int`\ ) |const| :ref:`🔗` -Return true whether the stream associated with an integer ID is still playing. Check :ref:`play_stream` for information on when this ID becomes invalid. +Returns ``true`` if the stream associated with the given integer ID is still playing. Check :ref:`play_stream()` for information on when this ID becomes invalid. .. rst-class:: classref-item-separator @@ -83,13 +83,13 @@ Return true whether the stream associated with an integer ID is still playing. C .. rst-class:: classref-method -:ref:`int` **play_stream**\ (\ stream\: :ref:`AudioStream`, from_offset\: :ref:`float` = 0, volume_db\: :ref:`float` = 0, pitch_scale\: :ref:`float` = 1.0\ ) +:ref:`int` **play_stream**\ (\ stream\: :ref:`AudioStream`, from_offset\: :ref:`float` = 0, volume_db\: :ref:`float` = 0, pitch_scale\: :ref:`float` = 1.0, playback_type\: :ref:`PlaybackType` = 0, bus\: :ref:`StringName` = &"Master"\ ) :ref:`🔗` -Play an :ref:`AudioStream` at a given offset, volume and pitch scale. Playback starts immediately. +Play an :ref:`AudioStream` at a given offset, volume, pitch scale, playback type, and bus. Playback starts immediately. 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. +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. This function returns :ref:`INVALID_ID` if the amount of streams currently playing equals :ref:`AudioStreamPolyphonic.polyphony`. If you need a higher amount of maximum polyphony, raise this value. @@ -101,9 +101,9 @@ This function returns :ref:`INVALID_ID`, pitch_scale\: :ref:`float`\ ) +|void| **set_stream_pitch_scale**\ (\ stream\: :ref:`int`, pitch_scale\: :ref:`float`\ ) :ref:`🔗` -Change the stream pitch scale. The ``stream`` argument is an integer ID returned by :ref:`play_stream`. +Change the stream pitch scale. The ``stream`` argument is an integer ID returned by :ref:`play_stream()`. .. rst-class:: classref-item-separator @@ -113,9 +113,9 @@ Change the stream pitch scale. The ``stream`` argument is an integer ID returned .. rst-class:: classref-method -|void| **set_stream_volume**\ (\ stream\: :ref:`int`, volume_db\: :ref:`float`\ ) +|void| **set_stream_volume**\ (\ stream\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` -Change the stream volume (in db). The ``stream`` argument is an integer ID returned by :ref:`play_stream`. +Change the stream volume (in db). The ``stream`` argument is an integer ID returned by :ref:`play_stream()`. .. rst-class:: classref-item-separator @@ -125,11 +125,12 @@ Change the stream volume (in db). The ``stream`` argument is an integer ID retur .. rst-class:: classref-method -|void| **stop_stream**\ (\ stream\: :ref:`int`\ ) +|void| **stop_stream**\ (\ stream\: :ref:`int`\ ) :ref:`🔗` -Stop a stream. The ``stream`` argument is an integer ID returned by :ref:`play_stream`, which becomes invalid after calling this function. +Stop a stream. The ``stream`` argument is an integer ID returned by :ref:`play_stream()`, which becomes invalid after calling this function. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplaybackresampled.rst b/classes/class_audiostreamplaybackresampled.rst index 82db9bfa954..9fcafec2cc5 100644 --- a/classes/class_audiostreamplaybackresampled.rst +++ b/classes/class_audiostreamplaybackresampled.rst @@ -26,13 +26,13 @@ Methods .. table:: :widths: auto - +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_get_stream_sampling_rate`\ (\ ) |virtual| |const| | - +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`_mix_resampled`\ (\ dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| | - +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`begin_resample`\ (\ ) | - +---------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_get_stream_sampling_rate`\ (\ ) |virtual| |required| |const| | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`_mix_resampled`\ (\ dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`begin_resample`\ (\ ) | + +---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -47,7 +47,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **_get_stream_sampling_rate**\ (\ ) |virtual| |const| +:ref:`float` **_get_stream_sampling_rate**\ (\ ) |virtual| |required| |const| :ref:`🔗` .. container:: contribute @@ -61,7 +61,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`int` **_mix_resampled**\ (\ dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| +:ref:`int` **_mix_resampled**\ (\ dst_buffer\: ``AudioFrame*``, frame_count\: :ref:`int`\ ) |virtual| |required| :ref:`🔗` .. container:: contribute @@ -75,13 +75,14 @@ Method Descriptions .. rst-class:: classref-method -|void| **begin_resample**\ (\ ) +|void| **begin_resample**\ (\ ) :ref:`🔗` .. container:: contribute There is currently no description for this method. Please help us by :ref:`contributing one `! .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplaybacksynchronized.rst b/classes/class_audiostreamplaybacksynchronized.rst new file mode 100644 index 00000000000..4f39772353f --- /dev/null +++ b/classes/class_audiostreamplaybacksynchronized.rst @@ -0,0 +1,27 @@ +: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/modules/interactive_music/doc_classes/AudioStreamPlaybackSynchronized.xml. + +.. _class_AudioStreamPlaybackSynchronized: + +AudioStreamPlaybackSynchronized +=============================== + +**Inherits:** :ref:`AudioStreamPlayback` **<** :ref:`RefCounted` **<** :ref:`Object` + +.. container:: contribute + + There is currently no description for this class. Please help us by :ref:`contributing one `! + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamplayer.rst b/classes/class_audiostreamplayer.rst index f6c43302ea2..ed301a53230 100644 --- a/classes/class_audiostreamplayer.rst +++ b/classes/class_audiostreamplayer.rst @@ -15,16 +15,18 @@ AudioStreamPlayer **Inherits:** :ref:`Node` **<** :ref:`Object` -Plays back audio non-positionally. +A node for audio playback. .. rst-class:: classref-introduction-group Description ----------- -Plays an audio stream non-positionally. +The **AudioStreamPlayer** node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music. -To play audio positionally, use :ref:`AudioStreamPlayer2D` or :ref:`AudioStreamPlayer3D` instead of **AudioStreamPlayer**. +To use this node, :ref:`stream` needs to be set to a valid :ref:`AudioStream` resource. Playing more than one sound at the same time is also supported, see :ref:`max_polyphony`. + +If you need to play audio at a specific position, use :ref:`AudioStreamPlayer2D` or :ref:`AudioStreamPlayer3D` instead. .. rst-class:: classref-introduction-group @@ -33,15 +35,15 @@ Tutorials - :doc:`Audio streams <../tutorials/audio/audio_streams>` -- `2D Dodge The Creeps Demo `__ +- `2D Dodge The Creeps Demo `__ -- `Audio Device Changer Demo `__ +- `Audio Device Changer Demo `__ -- `Audio Generator Demo `__ +- `Audio Generator Demo `__ -- `Audio Mic Record Demo `__ +- `Audio Microphone Record Demo `__ -- `Audio Spectrum Demo `__ +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -62,6 +64,8 @@ Properties +----------------------------------------------------+----------------------------------------------------------------------+---------------+ | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`PlaybackType` | :ref:`playback_type` | ``0`` | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ | :ref:`bool` | :ref:`playing` | ``false`` | +----------------------------------------------------+----------------------------------------------------------------------+---------------+ | :ref:`AudioStream` | :ref:`stream` | | @@ -70,6 +74,8 @@ Properties +----------------------------------------------------+----------------------------------------------------------------------+---------------+ | :ref:`float` | :ref:`volume_db` | ``0.0`` | +----------------------------------------------------+----------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_linear` | | + +----------------------------------------------------+----------------------------------------------------------------------+---------------+ .. rst-class:: classref-reftable-group @@ -106,9 +112,9 @@ Signals .. rst-class:: classref-signal -**finished**\ (\ ) +**finished**\ (\ ) :ref:`🔗` -Emitted when the audio stops playing. +Emitted when a sound finishes playing without interruptions. This signal is *not* emitted when calling :ref:`stop()`, or when exiting the tree while sounds are playing. .. rst-class:: classref-section-separator @@ -123,7 +129,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **MixTarget**: +enum **MixTarget**: :ref:`🔗` .. _class_AudioStreamPlayer_constant_MIX_TARGET_STEREO: @@ -131,7 +137,7 @@ enum **MixTarget**: :ref:`MixTarget` **MIX_TARGET_STEREO** = ``0`` -The audio will be played only on the first channel. +The audio will be played only on the first channel. This is the default. .. _class_AudioStreamPlayer_constant_MIX_TARGET_SURROUND: @@ -162,14 +168,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **autoplay** = ``false`` +:ref:`bool` **autoplay** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_autoplay**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_autoplay_enabled**\ (\ ) -If ``true``, audio plays when added to scene tree. +If ``true``, this node calls :ref:`play()` when entering the tree. .. rst-class:: classref-item-separator @@ -179,16 +185,16 @@ If ``true``, audio plays when added to scene tree. .. rst-class:: classref-property -:ref:`StringName` **bus** = ``&"Master"`` +:ref:`StringName` **bus** = ``&"Master"`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_bus**\ (\ value\: :ref:`StringName`\ ) - :ref:`StringName` **get_bus**\ (\ ) -Bus on which this audio is playing. +The target bus name. All sounds from this node will be playing on this bus. -\ **Note:** When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to ``"Master"``. +\ **Note:** At runtime, if no bus with the given name exists, all sounds will fall back on ``"Master"``. See also :ref:`AudioServer.get_bus_name()`. .. rst-class:: classref-item-separator @@ -198,14 +204,14 @@ Bus on which this audio is playing. .. rst-class:: classref-property -:ref:`int` **max_polyphony** = ``1`` +:ref:`int` **max_polyphony** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_max_polyphony**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_max_polyphony**\ (\ ) -The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds. +The maximum number of sounds this node can play at the same time. Calling :ref:`play()` after this value is reached will cut off the oldest sounds. .. rst-class:: classref-item-separator @@ -215,14 +221,14 @@ The maximum number of sounds this node can play at the same time. Playing additi .. rst-class:: classref-property -:ref:`MixTarget` **mix_target** = ``0`` +:ref:`MixTarget` **mix_target** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_mix_target**\ (\ value\: :ref:`MixTarget`\ ) - :ref:`MixTarget` **get_mix_target**\ (\ ) -If the audio configuration has more than two speakers, this sets the target channels. See :ref:`MixTarget` constants. +The mix target channels. Has no effect when two speakers or less are detected (see :ref:`SpeakerMode`). .. rst-class:: classref-item-separator @@ -232,14 +238,33 @@ If the audio configuration has more than two speakers, this sets the target chan .. rst-class:: classref-property -:ref:`float` **pitch_scale** = ``1.0`` +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_pitch_scale**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_pitch_scale**\ (\ ) -The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. +The audio's pitch and tempo, as a multiplier of the :ref:`stream`'s sample rate. A value of ``2.0`` doubles the audio's pitch, while a value of ``0.5`` halves the pitch. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer_property_playback_type: + +.. rst-class:: classref-property + +:ref:`PlaybackType` **playback_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_type**\ (\ value\: :ref:`PlaybackType`\ ) +- :ref:`PlaybackType` **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. .. rst-class:: classref-item-separator @@ -249,13 +274,14 @@ The pitch and the tempo of the audio, as a multiplier of the audio sample's samp .. rst-class:: classref-property -:ref:`bool` **playing** = ``false`` +:ref:`bool` **playing** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_playing**\ (\ ) -If ``true``, audio is playing. +If ``true``, this node is playing sounds. Setting this property has the same effect as :ref:`play()` and :ref:`stop()`. .. rst-class:: classref-item-separator @@ -265,14 +291,14 @@ If ``true``, audio is playing. .. rst-class:: classref-property -:ref:`AudioStream` **stream** +:ref:`AudioStream` **stream** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_stream**\ (\ value\: :ref:`AudioStream`\ ) - :ref:`AudioStream` **get_stream**\ (\ ) -The :ref:`AudioStream` object to be played. +The :ref:`AudioStream` resource to be played. Setting this property stops all currently playing sounds. If left empty, the **AudioStreamPlayer** does not work. .. rst-class:: classref-item-separator @@ -282,14 +308,16 @@ The :ref:`AudioStream` object to be played. .. rst-class:: classref-property -:ref:`bool` **stream_paused** = ``false`` +:ref:`bool` **stream_paused** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_stream_paused**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_stream_paused**\ (\ ) -If ``true``, the playback is paused. You can resume it by setting :ref:`stream_paused` to ``false``. +If ``true``, the sounds are paused. Setting :ref:`stream_paused` to ``false`` resumes all sounds. + +\ **Note:** This property is automatically changed when exiting or entering the tree, or this node is paused (see :ref:`Node.process_mode`). .. rst-class:: classref-item-separator @@ -299,14 +327,35 @@ If ``true``, the playback is paused. You can resume it by setting :ref:`stream_p .. rst-class:: classref-property -:ref:`float` **volume_db** = ``0.0`` +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_volume_db**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_volume_db**\ (\ ) -Volume of sound, in dB. +Volume of sound, in decibels. This is an offset of the :ref:`stream`'s volume. + +\ **Note:** To convert between decibel and linear energy (like most volume sliders do), use :ref:`volume_linear`, or :ref:`@GlobalScope.db_to_linear()` and :ref:`@GlobalScope.linear_to_db()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer_property_volume_linear: + +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +Volume of sound, as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. .. rst-class:: classref-section-separator @@ -321,9 +370,13 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_playback_position**\ (\ ) +:ref:`float` **get_playback_position**\ (\ ) :ref:`🔗` + +Returns the position in the :ref:`AudioStream` of the latest sound, in seconds. Returns ``0.0`` if no sounds are playing. + +\ **Note:** The position is not always accurate, as the :ref:`AudioServer` does not mix audio every processed frame. To get more accurate results, add :ref:`AudioServer.get_time_since_last_mix()` to the returned position. -Returns the position in the :ref:`AudioStream` in seconds. +\ **Note:** This method always returns ``0.0`` if the :ref:`stream` is an :ref:`AudioStreamInteractive`, since it can have multiple clips playing at once. .. rst-class:: classref-item-separator @@ -333,9 +386,9 @@ Returns the position in the :ref:`AudioStream` in seconds. .. rst-class:: classref-method -:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) +:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) :ref:`🔗` -Returns the :ref:`AudioStreamPlayback` object associated with this **AudioStreamPlayer**. +Returns the latest :ref:`AudioStreamPlayback` of this node, usually the most recently created by :ref:`play()`. If no sounds are playing, this method fails and returns an empty playback. .. rst-class:: classref-item-separator @@ -345,9 +398,9 @@ Returns the :ref:`AudioStreamPlayback` object associa .. rst-class:: classref-method -:ref:`bool` **has_stream_playback**\ (\ ) +:ref:`bool` **has_stream_playback**\ (\ ) :ref:`🔗` -Returns whether the **AudioStreamPlayer** can return the :ref:`AudioStreamPlayback` object or not. +Returns ``true`` if any sound is active, even if :ref:`stream_paused` is set to ``true``. See also :ref:`playing` and :ref:`get_stream_playback()`. .. rst-class:: classref-item-separator @@ -357,9 +410,9 @@ Returns whether the **AudioStreamPlayer** can return the :ref:`AudioStreamPlayba .. rst-class:: classref-method -|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) +|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) :ref:`🔗` -Plays the audio from the given ``from_position``, in seconds. +Plays a sound from the beginning, or the given ``from_position`` in seconds. .. rst-class:: classref-item-separator @@ -369,9 +422,9 @@ Plays the audio from the given ``from_position``, in seconds. .. rst-class:: classref-method -|void| **seek**\ (\ to_position\: :ref:`float`\ ) +|void| **seek**\ (\ to_position\: :ref:`float`\ ) :ref:`🔗` -Sets the position from which audio will be played, in seconds. +Restarts all sounds to be played from the given ``to_position``, in seconds. Does nothing if no sounds are playing. .. rst-class:: classref-item-separator @@ -381,11 +434,12 @@ Sets the position from which audio will be played, in seconds. .. rst-class:: classref-method -|void| **stop**\ (\ ) +|void| **stop**\ (\ ) :ref:`🔗` -Stops the audio. +Stops all sounds from this node. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplayer2d.rst b/classes/class_audiostreamplayer2d.rst index 1a055f6d5f5..08b9b80e522 100644 --- a/classes/class_audiostreamplayer2d.rst +++ b/classes/class_audiostreamplayer2d.rst @@ -24,7 +24,7 @@ Description Plays audio that is attenuated with distance to the listener. -By default, audio is heard from the screen center. This can be changed by adding an :ref:`AudioListener2D` node to the scene and enabling it by calling :ref:`AudioListener2D.make_current` on it. +By default, audio is heard from the screen center. This can be changed by adding an :ref:`AudioListener2D` node to the scene and enabling it by calling :ref:`AudioListener2D.make_current()` on it. See also :ref:`AudioStreamPlayer` to play a sound non-positionally. @@ -45,31 +45,35 @@ Properties .. table:: :widths: auto - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`int` | :ref:`area_mask` | ``1`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`float` | :ref:`attenuation` | ``1.0`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`bool` | :ref:`autoplay` | ``false`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`StringName` | :ref:`bus` | ``&"Master"`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`float` | :ref:`max_distance` | ``2000.0`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`int` | :ref:`max_polyphony` | ``1`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`float` | :ref:`panning_strength` | ``1.0`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`bool` | :ref:`playing` | ``false`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`AudioStream` | :ref:`stream` | | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`bool` | :ref:`stream_paused` | ``false`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ - | :ref:`float` | :ref:`volume_db` | ``0.0`` | - +---------------------------------------+------------------------------------------------------------------------------+---------------+ + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`area_mask` | ``1`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`attenuation` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`autoplay` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`StringName` | :ref:`bus` | ``&"Master"`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`max_distance` | ``2000.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`int` | :ref:`max_polyphony` | ``1`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`panning_strength` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`PlaybackType` | :ref:`playback_type` | ``0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`playing` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`AudioStream` | :ref:`stream` | | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`bool` | :ref:`stream_paused` | ``false`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_db` | ``0.0`` | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_linear` | | + +----------------------------------------------------+------------------------------------------------------------------------------+---------------+ .. rst-class:: classref-reftable-group @@ -106,7 +110,7 @@ Signals .. rst-class:: classref-signal -**finished**\ (\ ) +**finished**\ (\ ) :ref:`🔗` Emitted when the audio stops playing. @@ -123,7 +127,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **area_mask** = ``1`` +:ref:`int` **area_mask** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -140,7 +144,7 @@ Determines which :ref:`Area2D` layers affect the sound for reverb .. rst-class:: classref-property -:ref:`float` **attenuation** = ``1.0`` +:ref:`float` **attenuation** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -157,7 +161,7 @@ The volume is attenuated over distance with this as an exponent. .. rst-class:: classref-property -:ref:`bool` **autoplay** = ``false`` +:ref:`bool` **autoplay** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -174,7 +178,7 @@ If ``true``, audio plays when added to scene tree. .. rst-class:: classref-property -:ref:`StringName` **bus** = ``&"Master"`` +:ref:`StringName` **bus** = ``&"Master"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -193,7 +197,7 @@ Bus on which this audio is playing. .. rst-class:: classref-property -:ref:`float` **max_distance** = ``2000.0`` +:ref:`float` **max_distance** = ``2000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -210,7 +214,7 @@ Maximum distance from which audio is still hearable. .. rst-class:: classref-property -:ref:`int` **max_polyphony** = ``1`` +:ref:`int` **max_polyphony** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -227,7 +231,7 @@ The maximum number of sounds this node can play at the same time. Playing additi .. rst-class:: classref-property -:ref:`float` **panning_strength** = ``1.0`` +:ref:`float` **panning_strength** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -244,7 +248,7 @@ Scales the panning strength for this node by multiplying the base :ref:`ProjectS .. rst-class:: classref-property -:ref:`float` **pitch_scale** = ``1.0`` +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -257,17 +261,37 @@ The pitch and the tempo of the audio, as a multiplier of the audio sample's samp ---- +.. _class_AudioStreamPlayer2D_property_playback_type: + +.. rst-class:: classref-property + +:ref:`PlaybackType` **playback_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_type**\ (\ value\: :ref:`PlaybackType`\ ) +- :ref:`PlaybackType` **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStreamPlayer2D_property_playing: .. rst-class:: classref-property -:ref:`bool` **playing** = ``false`` +:ref:`bool` **playing** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_playing**\ (\ ) -If ``true``, audio is playing or is queued to be played (see :ref:`play`). +If ``true``, audio is playing or is queued to be played (see :ref:`play()`). .. rst-class:: classref-item-separator @@ -277,7 +301,7 @@ If ``true``, audio is playing or is queued to be played (see :ref:`play` **stream** +:ref:`AudioStream` **stream** :ref:`🔗` .. rst-class:: classref-property-setget @@ -294,7 +318,7 @@ The :ref:`AudioStream` object to be played. .. rst-class:: classref-property -:ref:`bool` **stream_paused** = ``false`` +:ref:`bool` **stream_paused** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -311,14 +335,33 @@ If ``true``, the playback is paused. You can resume it by setting :ref:`stream_p .. rst-class:: classref-property -:ref:`float` **volume_db** = ``0.0`` +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_volume_db**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_volume_db**\ (\ ) -Base volume before attenuation. +Base volume before attenuation, in decibels. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer2D_property_volume_linear: + +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +Base volume before attenuation, as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. .. rst-class:: classref-section-separator @@ -333,7 +376,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_playback_position**\ (\ ) +:ref:`float` **get_playback_position**\ (\ ) :ref:`🔗` Returns the position in the :ref:`AudioStream`. @@ -345,7 +388,7 @@ Returns the position in the :ref:`AudioStream`. .. rst-class:: classref-method -:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) +:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) :ref:`🔗` Returns the :ref:`AudioStreamPlayback` object associated with this **AudioStreamPlayer2D**. @@ -357,7 +400,7 @@ Returns the :ref:`AudioStreamPlayback` object associa .. rst-class:: classref-method -:ref:`bool` **has_stream_playback**\ (\ ) +:ref:`bool` **has_stream_playback**\ (\ ) :ref:`🔗` Returns whether the :ref:`AudioStreamPlayer` can return the :ref:`AudioStreamPlayback` object or not. @@ -369,7 +412,7 @@ Returns whether the :ref:`AudioStreamPlayer` can return .. rst-class:: classref-method -|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) +|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) :ref:`🔗` Queues the audio to play on the next physics frame, from the given position ``from_position``, in seconds. @@ -381,7 +424,7 @@ Queues the audio to play on the next physics frame, from the given position ``fr .. rst-class:: classref-method -|void| **seek**\ (\ to_position\: :ref:`float`\ ) +|void| **seek**\ (\ to_position\: :ref:`float`\ ) :ref:`🔗` Sets the position from which audio will be played, in seconds. @@ -393,11 +436,12 @@ Sets the position from which audio will be played, in seconds. .. rst-class:: classref-method -|void| **stop**\ (\ ) +|void| **stop**\ (\ ) :ref:`🔗` Stops the audio. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplayer3d.rst b/classes/class_audiostreamplayer3d.rst index be810990ac8..eef1a42c4fe 100644 --- a/classes/class_audiostreamplayer3d.rst +++ b/classes/class_audiostreamplayer3d.rst @@ -24,7 +24,7 @@ Description Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting :ref:`attenuation_filter_cutoff_hz` to ``20500``. -By default, audio is heard from the camera position. This can be changed by adding an :ref:`AudioListener3D` node to the scene and enabling it by calling :ref:`AudioListener3D.make_current` on it. +By default, audio is heard from the camera position. This can be changed by adding an :ref:`AudioListener3D` node to the scene and enabling it by calling :ref:`AudioListener3D.make_current()` on it. See also :ref:`AudioStreamPlayer` to play a sound non-positionally. @@ -76,6 +76,8 @@ Properties +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ | :ref:`float` | :ref:`pitch_scale` | ``1.0`` | +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`PlaybackType` | :ref:`playback_type` | ``0`` | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ | :ref:`bool` | :ref:`playing` | ``false`` | +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ | :ref:`AudioStream` | :ref:`stream` | | @@ -86,6 +88,8 @@ Properties +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ | :ref:`float` | :ref:`volume_db` | ``0.0`` | +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`volume_linear` | | + +--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+ .. rst-class:: classref-reftable-group @@ -122,7 +126,7 @@ Signals .. rst-class:: classref-signal -**finished**\ (\ ) +**finished**\ (\ ) :ref:`🔗` Emitted when the audio stops playing. @@ -139,7 +143,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **AttenuationModel**: +enum **AttenuationModel**: :ref:`🔗` .. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_DISTANCE: @@ -181,7 +185,7 @@ No attenuation of loudness according to distance. The sound will still be heard .. rst-class:: classref-enumeration -enum **DopplerTracking**: +enum **DopplerTracking**: :ref:`🔗` .. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_DISABLED: @@ -220,7 +224,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **area_mask** = ``1`` +:ref:`int` **area_mask** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -237,7 +241,7 @@ Determines which :ref:`Area3D` layers affect the sound for reverb .. rst-class:: classref-property -:ref:`float` **attenuation_filter_cutoff_hz** = ``5000.0`` +:ref:`float` **attenuation_filter_cutoff_hz** = ``5000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -254,7 +258,7 @@ The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above th .. rst-class:: classref-property -:ref:`float` **attenuation_filter_db** = ``-24.0`` +:ref:`float` **attenuation_filter_db** = ``-24.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -271,7 +275,7 @@ Amount how much the filter affects the loudness, in decibels. .. rst-class:: classref-property -:ref:`AttenuationModel` **attenuation_model** = ``0`` +:ref:`AttenuationModel` **attenuation_model** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -288,7 +292,7 @@ Decides if audio should get quieter with distance linearly, quadratically, logar .. rst-class:: classref-property -:ref:`bool` **autoplay** = ``false`` +:ref:`bool` **autoplay** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -305,7 +309,7 @@ If ``true``, audio plays when the AudioStreamPlayer3D node is added to scene tre .. rst-class:: classref-property -:ref:`StringName` **bus** = ``&"Master"`` +:ref:`StringName` **bus** = ``&"Master"`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -324,7 +328,7 @@ The bus on which this audio is playing. .. rst-class:: classref-property -:ref:`DopplerTracking` **doppler_tracking** = ``0`` +:ref:`DopplerTracking` **doppler_tracking** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -333,6 +337,8 @@ The bus on which this audio is playing. Decides in which step the Doppler effect should be calculated. +\ **Note:** If :ref:`doppler_tracking` is not :ref:`DOPPLER_TRACKING_DISABLED` but the current :ref:`Camera3D`/:ref:`AudioListener3D` has doppler tracking disabled, the Doppler effect will be heard but will not take the movement of the current listener into account. If accurate Doppler effect is desired, doppler tracking should be enabled on both the **AudioStreamPlayer3D** and the current :ref:`Camera3D`/:ref:`AudioListener3D`. + .. rst-class:: classref-item-separator ---- @@ -341,7 +347,7 @@ Decides in which step the Doppler effect should be calculated. .. rst-class:: classref-property -:ref:`float` **emission_angle_degrees** = ``45.0`` +:ref:`float` **emission_angle_degrees** = ``45.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -358,7 +364,7 @@ The angle in which the audio reaches a listener unattenuated. .. rst-class:: classref-property -:ref:`bool` **emission_angle_enabled** = ``false`` +:ref:`bool` **emission_angle_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -375,7 +381,7 @@ If ``true``, the audio should be attenuated according to the direction of the so .. rst-class:: classref-property -:ref:`float` **emission_angle_filter_attenuation_db** = ``-12.0`` +:ref:`float` **emission_angle_filter_attenuation_db** = ``-12.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -392,7 +398,7 @@ Attenuation factor used if listener is outside of :ref:`emission_angle_degrees` **max_db** = ``3.0`` +:ref:`float` **max_db** = ``3.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -409,7 +415,7 @@ Sets the absolute maximum of the sound level, in decibels. .. rst-class:: classref-property -:ref:`float` **max_distance** = ``0.0`` +:ref:`float` **max_distance** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -426,7 +432,7 @@ The distance past which the sound can no longer be heard at all. Only has an eff .. rst-class:: classref-property -:ref:`int` **max_polyphony** = ``1`` +:ref:`int` **max_polyphony** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -443,14 +449,18 @@ The maximum number of sounds this node can play at the same time. Playing additi .. rst-class:: classref-property -:ref:`float` **panning_strength** = ``1.0`` +:ref:`float` **panning_strength** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_panning_strength**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_panning_strength**\ (\ ) -Scales the panning strength for this node by multiplying the base :ref:`ProjectSettings.audio/general/3d_panning_strength` with this factor. Higher values will pan audio from left to right more dramatically than lower values. +Scales the panning strength for this node by multiplying the base :ref:`ProjectSettings.audio/general/3d_panning_strength` by this factor. If the product is ``0.0`` then stereo panning is disabled and the volume is the same for all channels. If the product is ``1.0`` then one of the channels will be muted when the sound is located exactly to the left (or right) of the listener. + +Two speaker stereo arrangements implement the `WebAudio standard for StereoPannerNode Panning `__ where the volume is cosine of half the azimuth angle to the ear. + +For other speaker arrangements such as the 5.1 and 7.1 the SPCAP (Speaker-Placement Correction Amplitude) algorithm is implemented. .. rst-class:: classref-item-separator @@ -460,7 +470,7 @@ Scales the panning strength for this node by multiplying the base :ref:`ProjectS .. rst-class:: classref-property -:ref:`float` **pitch_scale** = ``1.0`` +:ref:`float` **pitch_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -473,17 +483,37 @@ The pitch and the tempo of the audio, as a multiplier of the audio sample's samp ---- +.. _class_AudioStreamPlayer3D_property_playback_type: + +.. rst-class:: classref-property + +:ref:`PlaybackType` **playback_type** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_playback_type**\ (\ value\: :ref:`PlaybackType`\ ) +- :ref:`PlaybackType` **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStreamPlayer3D_property_playing: .. rst-class:: classref-property -:ref:`bool` **playing** = ``false`` +:ref:`bool` **playing** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_playing**\ (\ ) -If ``true``, audio is playing or is queued to be played (see :ref:`play`). +If ``true``, audio is playing or is queued to be played (see :ref:`play()`). .. rst-class:: classref-item-separator @@ -493,7 +523,7 @@ If ``true``, audio is playing or is queued to be played (see :ref:`play` **stream** +:ref:`AudioStream` **stream** :ref:`🔗` .. rst-class:: classref-property-setget @@ -510,7 +540,7 @@ The :ref:`AudioStream` resource to be played. .. rst-class:: classref-property -:ref:`bool` **stream_paused** = ``false`` +:ref:`bool` **stream_paused** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -527,7 +557,7 @@ If ``true``, the playback is paused. You can resume it by setting :ref:`stream_p .. rst-class:: classref-property -:ref:`float` **unit_size** = ``10.0`` +:ref:`float` **unit_size** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -544,7 +574,7 @@ The factor for the attenuation effect. Higher values make the sound audible over .. rst-class:: classref-property -:ref:`float` **volume_db** = ``0.0`` +:ref:`float` **volume_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -553,6 +583,25 @@ The factor for the attenuation effect. Higher values make the sound audible over The base sound level before attenuation, in decibels. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayer3D_property_volume_linear: + +.. rst-class:: classref-property + +:ref:`float` **volume_linear** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_volume_linear**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_volume_linear**\ (\ ) + +The base sound level before attenuation, as a linear value. + +\ **Note:** This member modifies :ref:`volume_db` for convenience. The returned value is equivalent to the result of :ref:`@GlobalScope.db_to_linear()` on :ref:`volume_db`. Setting this member is equivalent to setting :ref:`volume_db` to the result of :ref:`@GlobalScope.linear_to_db()` on a value. + .. rst-class:: classref-section-separator ---- @@ -566,7 +615,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_playback_position**\ (\ ) +:ref:`float` **get_playback_position**\ (\ ) :ref:`🔗` Returns the position in the :ref:`AudioStream`. @@ -578,7 +627,7 @@ Returns the position in the :ref:`AudioStream`. .. rst-class:: classref-method -:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) +:ref:`AudioStreamPlayback` **get_stream_playback**\ (\ ) :ref:`🔗` Returns the :ref:`AudioStreamPlayback` object associated with this **AudioStreamPlayer3D**. @@ -590,7 +639,7 @@ Returns the :ref:`AudioStreamPlayback` object associa .. rst-class:: classref-method -:ref:`bool` **has_stream_playback**\ (\ ) +:ref:`bool` **has_stream_playback**\ (\ ) :ref:`🔗` Returns whether the :ref:`AudioStreamPlayer` can return the :ref:`AudioStreamPlayback` object or not. @@ -602,7 +651,7 @@ Returns whether the :ref:`AudioStreamPlayer` can return .. rst-class:: classref-method -|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) +|void| **play**\ (\ from_position\: :ref:`float` = 0.0\ ) :ref:`🔗` Queues the audio to play on the next physics frame, from the given position ``from_position``, in seconds. @@ -614,7 +663,7 @@ Queues the audio to play on the next physics frame, from the given position ``fr .. rst-class:: classref-method -|void| **seek**\ (\ to_position\: :ref:`float`\ ) +|void| **seek**\ (\ to_position\: :ref:`float`\ ) :ref:`🔗` Sets the position from which audio will be played, in seconds. @@ -626,11 +675,12 @@ Sets the position from which audio will be played, in seconds. .. rst-class:: classref-method -|void| **stop**\ (\ ) +|void| **stop**\ (\ ) :ref:`🔗` Stops the audio. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamplaylist.rst b/classes/class_audiostreamplaylist.rst new file mode 100644 index 00000000000..35766913c82 --- /dev/null +++ b/classes/class_audiostreamplaylist.rst @@ -0,0 +1,190 @@ +: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/modules/interactive_music/doc_classes/AudioStreamPlaylist.xml. + +.. _class_AudioStreamPlaylist: + +AudioStreamPlaylist +=================== + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +:ref:`AudioStream` that includes sub-streams and plays them back like a playlist. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`float` | :ref:`fade_time` | ``0.3`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`loop` | ``true`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`shuffle` | ``false`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + | :ref:`int` | :ref:`stream_count` | ``0`` | + +---------------------------+----------------------------------------------------------------------+-----------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_bpm`\ (\ ) |const| | + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_list_stream`\ (\ stream_index\: :ref:`int`\ ) |const| | + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_list_stream`\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) | + +---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamPlaylist_constant_MAX_STREAMS: + +.. rst-class:: classref-constant + +**MAX_STREAMS** = ``64`` :ref:`🔗` + +Maximum amount of streams supported in the playlist. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamPlaylist_property_fade_time: + +.. rst-class:: classref-property + +:ref:`float` **fade_time** = ``0.3`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fade_time**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fade_time**\ (\ ) + +Fade time used when a stream ends, when going to the next one. Streams are expected to have an extra bit of audio after the end to help with fading. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_property_loop: + +.. rst-class:: classref-property + +:ref:`bool` **loop** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_loop**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **has_loop**\ (\ ) + +If ``true``, the playlist will loop, otherwise the playlist will end when the last stream is finished. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_property_shuffle: + +.. rst-class:: classref-property + +:ref:`bool` **shuffle** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_shuffle**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_shuffle**\ (\ ) + +If ``true``, the playlist will shuffle each time playback starts and each time it loops. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_property_stream_count: + +.. rst-class:: classref-property + +:ref:`int` **stream_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stream_count**\ (\ ) + +Amount of streams in the playlist. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamPlaylist_method_get_bpm: + +.. rst-class:: classref-method + +:ref:`float` **get_bpm**\ (\ ) |const| :ref:`🔗` + +Returns the BPM of the playlist, which can vary depending on the clip being played. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_method_get_list_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_list_stream**\ (\ stream_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the stream at playback position index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlaylist_method_set_list_stream: + +.. rst-class:: classref-method + +|void| **set_list_stream**\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Sets the stream at playback position index. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreampolyphonic.rst b/classes/class_audiostreampolyphonic.rst index 2e078fe2781..47ff2136ae8 100644 --- a/classes/class_audiostreampolyphonic.rst +++ b/classes/class_audiostreampolyphonic.rst @@ -21,7 +21,7 @@ Description AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player. -Playback control is done via the :ref:`AudioStreamPlaybackPolyphonic` instance set inside the player, which can be obtained via :ref:`AudioStreamPlayer.get_stream_playback`, :ref:`AudioStreamPlayer2D.get_stream_playback` or :ref:`AudioStreamPlayer3D.get_stream_playback` methods. Obtaining the playback instance is only valid after the ``stream`` property is set as an **AudioStreamPolyphonic** in those players. +Playback control is done via the :ref:`AudioStreamPlaybackPolyphonic` instance set inside the player, which can be obtained via :ref:`AudioStreamPlayer.get_stream_playback()`, :ref:`AudioStreamPlayer2D.get_stream_playback()` or :ref:`AudioStreamPlayer3D.get_stream_playback()` methods. Obtaining the playback instance is only valid after the ``stream`` property is set as an **AudioStreamPolyphonic** in those players. .. rst-class:: classref-reftable-group @@ -48,7 +48,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **polyphony** = ``32`` +:ref:`int` **polyphony** = ``32`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -58,6 +58,7 @@ Property Descriptions Maximum amount of simultaneous streams that can be played. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamrandomizer.rst b/classes/class_audiostreamrandomizer.rst index 0834a902257..f5237f73005 100644 --- a/classes/class_audiostreamrandomizer.rst +++ b/classes/class_audiostreamrandomizer.rst @@ -76,7 +76,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **PlaybackMode**: +enum **PlaybackMode**: :ref:`🔗` .. _class_AudioStreamRandomizer_constant_PLAYBACK_RANDOM_NO_REPEATS: @@ -115,7 +115,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`PlaybackMode` **playback_mode** = ``0`` +:ref:`PlaybackMode` **playback_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -132,7 +132,7 @@ Controls how this AudioStreamRandomizer picks which AudioStream to play next. .. rst-class:: classref-property -:ref:`float` **random_pitch** = ``1.0`` +:ref:`float` **random_pitch** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -149,7 +149,7 @@ The intensity of random pitch variation. A value of 1 means no variation. .. rst-class:: classref-property -:ref:`float` **random_volume_offset_db** = ``0.0`` +:ref:`float` **random_volume_offset_db** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -166,7 +166,7 @@ The intensity of random volume variation. A value of 0 means no variation. .. rst-class:: classref-property -:ref:`int` **streams_count** = ``0`` +:ref:`int` **streams_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -188,7 +188,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_stream**\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`, weight\: :ref:`float` = 1.0\ ) +|void| **add_stream**\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`, weight\: :ref:`float` = 1.0\ ) :ref:`🔗` Insert a stream at the specified index. If the index is less than zero, the insertion occurs at the end of the underlying pool. @@ -200,7 +200,7 @@ Insert a stream at the specified index. If the index is less than zero, the inse .. rst-class:: classref-method -:ref:`AudioStream` **get_stream**\ (\ index\: :ref:`int`\ ) |const| +:ref:`AudioStream` **get_stream**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the stream at the specified index. @@ -212,7 +212,7 @@ Returns the stream at the specified index. .. rst-class:: classref-method -:ref:`float` **get_stream_probability_weight**\ (\ index\: :ref:`int`\ ) |const| +:ref:`float` **get_stream_probability_weight**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the probability weight associated with the stream at the given index. @@ -224,7 +224,7 @@ Returns the probability weight associated with the stream at the given index. .. rst-class:: classref-method -|void| **move_stream**\ (\ index_from\: :ref:`int`, index_to\: :ref:`int`\ ) +|void| **move_stream**\ (\ index_from\: :ref:`int`, index_to\: :ref:`int`\ ) :ref:`🔗` Move a stream from one index to another. @@ -236,7 +236,7 @@ Move a stream from one index to another. .. rst-class:: classref-method -|void| **remove_stream**\ (\ index\: :ref:`int`\ ) +|void| **remove_stream**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Remove the stream at the specified index. @@ -248,7 +248,7 @@ Remove the stream at the specified index. .. rst-class:: classref-method -|void| **set_stream**\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) +|void| **set_stream**\ (\ index\: :ref:`int`, stream\: :ref:`AudioStream`\ ) :ref:`🔗` Set the AudioStream at the specified index. @@ -260,11 +260,12 @@ Set the AudioStream at the specified index. .. rst-class:: classref-method -|void| **set_stream_probability_weight**\ (\ index\: :ref:`int`, weight\: :ref:`float`\ ) +|void| **set_stream_probability_weight**\ (\ index\: :ref:`int`, weight\: :ref:`float`\ ) :ref:`🔗` Set the probability weight of the stream at the specified index. The higher this value, the more likely that the randomizer will choose this stream during random playback modes. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_audiostreamsynchronized.rst b/classes/class_audiostreamsynchronized.rst new file mode 100644 index 00000000000..f23f12b9553 --- /dev/null +++ b/classes/class_audiostreamsynchronized.rst @@ -0,0 +1,154 @@ +: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/modules/interactive_music/doc_classes/AudioStreamSynchronized.xml. + +.. _class_AudioStreamSynchronized: + +AudioStreamSynchronized +======================= + +**Inherits:** :ref:`AudioStream` **<** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +Stream that can be fitted with sub-streams, which will be played in-sync. + +.. rst-class:: classref-introduction-group + +Description +----------- + +This is a stream that can be fitted with sub-streams, which will be played in-sync. The streams begin at exactly the same time when play is pressed, and will end when the last of them ends. If one of the sub-streams loops, then playback will continue. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-----------------------+--------------------------------------------------------------------------+-------+ + | :ref:`int` | :ref:`stream_count` | ``0`` | + +-----------------------+--------------------------------------------------------------------------+-------+ + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStream` | :ref:`get_sync_stream`\ (\ stream_index\: :ref:`int`\ ) |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_sync_stream_volume`\ (\ stream_index\: :ref:`int`\ ) |const| | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_sync_stream`\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_sync_stream_volume`\ (\ stream_index\: :ref:`int`, volume_db\: :ref:`float`\ ) | + +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Constants +--------- + +.. _class_AudioStreamSynchronized_constant_MAX_STREAMS: + +.. rst-class:: classref-constant + +**MAX_STREAMS** = ``32`` :ref:`🔗` + +Maximum amount of streams that can be synchronized. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AudioStreamSynchronized_property_stream_count: + +.. rst-class:: classref-property + +:ref:`int` **stream_count** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stream_count**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stream_count**\ (\ ) + +Set the total amount of streams that will be played back synchronized. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_AudioStreamSynchronized_method_get_sync_stream: + +.. rst-class:: classref-method + +:ref:`AudioStream` **get_sync_stream**\ (\ stream_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Get one of the synchronized streams, by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamSynchronized_method_get_sync_stream_volume: + +.. rst-class:: classref-method + +:ref:`float` **get_sync_stream_volume**\ (\ stream_index\: :ref:`int`\ ) |const| :ref:`🔗` + +Get the volume of one of the synchronized streams, by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamSynchronized_method_set_sync_stream: + +.. rst-class:: classref-method + +|void| **set_sync_stream**\ (\ stream_index\: :ref:`int`, audio_stream\: :ref:`AudioStream`\ ) :ref:`🔗` + +Set one of the synchronized streams, by index. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamSynchronized_method_set_sync_stream_volume: + +.. rst-class:: classref-method + +|void| **set_sync_stream_volume**\ (\ stream_index\: :ref:`int`, volume_db\: :ref:`float`\ ) :ref:`🔗` + +Set the volume of one of the synchronized streams, by index. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_audiostreamwav.rst b/classes/class_audiostreamwav.rst index cc90f565894..ee54b00a1fc 100644 --- a/classes/class_audiostreamwav.rst +++ b/classes/class_audiostreamwav.rst @@ -53,6 +53,8 @@ Properties +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`stereo` | ``false`` | +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ + | :ref:`Dictionary` | :ref:`tags` | ``{}`` | + +-----------------------------------------------+-------------------------------------------------------------+-----------------------+ .. rst-class:: classref-reftable-group @@ -62,9 +64,13 @@ Methods .. table:: :widths: auto - +---------------------------------------+-------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`save_to_wav`\ (\ path\: :ref:`String`\ ) | - +---------------------------------------+-------------------------------------------------------------------------------------------------------+ + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamWAV` | :ref:`load_from_buffer`\ (\ stream_data\: :ref:`PackedByteArray`, options\: :ref:`Dictionary` = {}\ ) |static| | + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AudioStreamWAV` | :ref:`load_from_file`\ (\ path\: :ref:`String`, options\: :ref:`Dictionary` = {}\ ) |static| | + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`save_to_wav`\ (\ path\: :ref:`String`\ ) | + +---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -79,7 +85,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **Format**: +enum **Format**: :ref:`🔗` .. _class_AudioStreamWAV_constant_FORMAT_8_BITS: @@ -87,7 +93,7 @@ enum **Format**: :ref:`Format` **FORMAT_8_BITS** = ``0`` -8-bit audio codec. +8-bit PCM audio codec. .. _class_AudioStreamWAV_constant_FORMAT_16_BITS: @@ -95,7 +101,7 @@ enum **Format**: :ref:`Format` **FORMAT_16_BITS** = ``1`` -16-bit audio codec. +16-bit PCM audio codec. .. _class_AudioStreamWAV_constant_FORMAT_IMA_ADPCM: @@ -103,7 +109,15 @@ enum **Format**: :ref:`Format` **FORMAT_IMA_ADPCM** = ``2`` -Audio is compressed using IMA ADPCM. +Audio is lossily compressed as IMA ADPCM. + +.. _class_AudioStreamWAV_constant_FORMAT_QOA: + +.. rst-class:: classref-enumeration-constant + +:ref:`Format` **FORMAT_QOA** = ``3`` + +Audio is lossily compressed as `Quite OK Audio `__. .. rst-class:: classref-item-separator @@ -113,7 +127,7 @@ Audio is compressed using IMA ADPCM. .. rst-class:: classref-enumeration -enum **LoopMode**: +enum **LoopMode**: :ref:`🔗` .. _class_AudioStreamWAV_constant_LOOP_DISABLED: @@ -160,7 +174,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`PackedByteArray` **data** = ``PackedByteArray()`` +:ref:`PackedByteArray` **data** = ``PackedByteArray()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -169,7 +183,11 @@ Property Descriptions Contains the audio data in bytes. -\ **Note:** This property expects signed PCM8 data. To convert unsigned PCM8 to signed PCM8, subtract 128 from each byte. +\ **Note:** If :ref:`format` is set to :ref:`FORMAT_8_BITS`, this property expects signed 8-bit PCM data. To convert from unsigned 8-bit PCM, subtract 128 from each byte. + +\ **Note:** If :ref:`format` is set to :ref:`FORMAT_QOA`, this property expects data from a full QOA file. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedByteArray` for more details. .. rst-class:: classref-item-separator @@ -179,14 +197,14 @@ Contains the audio data in bytes. .. rst-class:: classref-property -:ref:`Format` **format** = ``0`` +:ref:`Format` **format** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_format**\ (\ value\: :ref:`Format`\ ) - :ref:`Format` **get_format**\ (\ ) -Audio format. See :ref:`Format` constants for values. +Audio format. .. rst-class:: classref-item-separator @@ -196,14 +214,14 @@ Audio format. See :ref:`Format` constants for values .. rst-class:: classref-property -:ref:`int` **loop_begin** = ``0`` +:ref:`int` **loop_begin** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_loop_begin**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_loop_begin**\ (\ ) -The loop start point (in number of samples, relative to the beginning of the sample). This information will be imported automatically from the WAV file if present. +The loop start point (in number of samples, relative to the beginning of the stream). .. rst-class:: classref-item-separator @@ -213,14 +231,14 @@ The loop start point (in number of samples, relative to the beginning of the sam .. rst-class:: classref-property -:ref:`int` **loop_end** = ``0`` +:ref:`int` **loop_end** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_loop_end**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_loop_end**\ (\ ) -The loop end point (in number of samples, relative to the beginning of the sample). This information will be imported automatically from the WAV file if present. +The loop end point (in number of samples, relative to the beginning of the stream). .. rst-class:: classref-item-separator @@ -230,14 +248,14 @@ The loop end point (in number of samples, relative to the beginning of the sampl .. rst-class:: classref-property -:ref:`LoopMode` **loop_mode** = ``0`` +:ref:`LoopMode` **loop_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) - :ref:`LoopMode` **get_loop_mode**\ (\ ) -The loop mode. This information will be imported automatically from the WAV file if present. See :ref:`LoopMode` constants for values. +The loop mode. .. rst-class:: classref-item-separator @@ -247,7 +265,7 @@ The loop mode. This information will be imported automatically from the WAV file .. rst-class:: classref-property -:ref:`int` **mix_rate** = ``44100`` +:ref:`int` **mix_rate** = ``44100`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -268,7 +286,7 @@ According to the `Nyquist-Shannon sampling theorem ` **stereo** = ``false`` +:ref:`bool` **stereo** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -277,6 +295,29 @@ According to the `Nyquist-Shannon sampling theorem ` **tags** = ``{}`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tags**\ (\ value\: :ref:`Dictionary`\ ) +- :ref:`Dictionary` **get_tags**\ (\ ) + +Contains user-defined tags if found in the WAV data. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date`` (``date`` does not have a standard date format). + +\ **Note:** No tag is *guaranteed* to be present in every file, so make sure to account for the keys not always existing. + +\ **Note:** Only WAV files using a ``LIST`` chunk with an identifier of ``INFO`` to encode the tags are currently supported. + .. rst-class:: classref-section-separator ---- @@ -286,17 +327,63 @@ If ``true``, audio is stereo. Method Descriptions ------------------- +.. _class_AudioStreamWAV_method_load_from_buffer: + +.. rst-class:: classref-method + +:ref:`AudioStreamWAV` **load_from_buffer**\ (\ stream_data\: :ref:`PackedByteArray`, options\: :ref:`Dictionary` = {}\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamWAV** instance from the given buffer. The buffer must contain WAV data. + +The keys and values of ``options`` match the properties of :ref:`ResourceImporterWAV`. The usage of ``options`` is identical to :ref:`load_from_file()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamWAV_method_load_from_file: + +.. rst-class:: classref-method + +:ref:`AudioStreamWAV` **load_from_file**\ (\ path\: :ref:`String`, options\: :ref:`Dictionary` = {}\ ) |static| :ref:`🔗` + +Creates a new **AudioStreamWAV** instance from the given file path. The file must be in WAV format. + +The keys and values of ``options`` match the properties of :ref:`ResourceImporterWAV`. + +\ **Example:** Load the first file dropped as a WAV and play it: + +:: + + @onready var audio_player = $AudioStreamPlayer + + func _ready(): + get_window().files_dropped.connect(_on_files_dropped) + + func _on_files_dropped(files): + if files[0].get_extension() == "wav": + audio_player.stream = AudioStreamWAV.load_from_file(files[0], { + "force/max_rate": true, + "force/max_rate_hz": 11025 + }) + audio_player.play() + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStreamWAV_method_save_to_wav: .. rst-class:: classref-method -:ref:`Error` **save_to_wav**\ (\ path\: :ref:`String`\ ) +:ref:`Error` **save_to_wav**\ (\ path\: :ref:`String`\ ) :ref:`🔗` -Saves the AudioStreamWAV as a WAV file to ``path``. Samples with IMA ADPCM format can't be saved. +Saves the AudioStreamWAV as a WAV file to ``path``. Samples with IMA ADPCM or Quite OK Audio formats can't be saved. \ **Note:** A ``.wav`` extension is automatically appended to ``path`` if it is missing. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_backbuffercopy.rst b/classes/class_backbuffercopy.rst index aa8cbd148b6..79a9ef70ace 100644 --- a/classes/class_backbuffercopy.rst +++ b/classes/class_backbuffercopy.rst @@ -23,6 +23,13 @@ Node for back-buffering the currently-displayed screen. The region defined in th \ **Note:** Since this node inherits from :ref:`Node2D` (and not :ref:`Control`), anchors and margins won't apply to child :ref:`Control`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control`-derived nodes as *siblings* to the **BackBufferCopy** node instead of adding them as children. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Screen-reading shaders <../tutorials/shaders/screen-reading_shaders>` + .. rst-class:: classref-reftable-group Properties @@ -50,7 +57,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **CopyMode**: +enum **CopyMode**: :ref:`🔗` .. _class_BackBufferCopy_constant_COPY_MODE_DISABLED: @@ -89,14 +96,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`CopyMode` **copy_mode** = ``1`` +:ref:`CopyMode` **copy_mode** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_copy_mode**\ (\ value\: :ref:`CopyMode`\ ) - :ref:`CopyMode` **get_copy_mode**\ (\ ) -Buffer mode. See :ref:`CopyMode` constants. +Buffer mode. .. rst-class:: classref-item-separator @@ -106,7 +113,7 @@ Buffer mode. See :ref:`CopyMode` constants. .. rst-class:: classref-property -:ref:`Rect2` **rect** = ``Rect2(-100, -100, 200, 200)`` +:ref:`Rect2` **rect** = ``Rect2(-100, -100, 200, 200)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -116,6 +123,7 @@ Buffer mode. See :ref:`CopyMode` constants. The area covered by the **BackBufferCopy**. Only used if :ref:`copy_mode` is :ref:`COPY_MODE_RECT`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_basebutton.rst b/classes/class_basebutton.rst index 7903421455c..d9e40d63ac8 100644 --- a/classes/class_basebutton.rst +++ b/classes/class_basebutton.rst @@ -88,7 +88,7 @@ Signals .. rst-class:: classref-signal -**button_down**\ (\ ) +**button_down**\ (\ ) :ref:`🔗` Emitted when the button starts being held down. @@ -100,7 +100,7 @@ Emitted when the button starts being held down. .. rst-class:: classref-signal -**button_up**\ (\ ) +**button_up**\ (\ ) :ref:`🔗` Emitted when the button stops being held down. @@ -112,7 +112,7 @@ Emitted when the button stops being held down. .. rst-class:: classref-signal -**pressed**\ (\ ) +**pressed**\ (\ ) :ref:`🔗` Emitted when the button is toggled or pressed. This is on :ref:`button_down` if :ref:`action_mode` is :ref:`ACTION_MODE_BUTTON_PRESS` and on :ref:`button_up` otherwise. @@ -126,7 +126,7 @@ If you need to know the button's pressed state (and :ref:`toggle_mode`\ ) +**toggled**\ (\ toggled_on\: :ref:`bool`\ ) :ref:`🔗` Emitted when the button was just toggled between pressed and normal states (only if :ref:`toggle_mode` is active). The new state is contained in the ``toggled_on`` argument. @@ -143,7 +143,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **DrawMode**: +enum **DrawMode**: :ref:`🔗` .. _class_BaseButton_constant_DRAW_NORMAL: @@ -193,7 +193,7 @@ The state of buttons are both hovered and pressed. .. rst-class:: classref-enumeration -enum **ActionMode**: +enum **ActionMode**: :ref:`🔗` .. _class_BaseButton_constant_ACTION_MODE_BUTTON_PRESS: @@ -224,14 +224,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`ActionMode` **action_mode** = ``1`` +:ref:`ActionMode` **action_mode** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_action_mode**\ (\ value\: :ref:`ActionMode`\ ) - :ref:`ActionMode` **get_action_mode**\ (\ ) -Determines when the button is considered clicked, one of the :ref:`ActionMode` constants. +Determines when the button is considered clicked. .. rst-class:: classref-item-separator @@ -241,7 +241,7 @@ Determines when the button is considered clicked, one of the :ref:`ActionMode` **button_group** +:ref:`ButtonGroup` **button_group** :ref:`🔗` .. rst-class:: classref-property-setget @@ -260,7 +260,7 @@ The :ref:`ButtonGroup` associated with the button. Not to be .. rst-class:: classref-property -|bitfield|\[:ref:`MouseButtonMask`\] **button_mask** = ``1`` +|bitfield|\[:ref:`MouseButtonMask`\] **button_mask** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -279,7 +279,7 @@ To allow both left-click and right-click, use ``MOUSE_BUTTON_MASK_LEFT | MOUSE_B .. rst-class:: classref-property -:ref:`bool` **button_pressed** = ``false`` +:ref:`bool` **button_pressed** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -288,7 +288,7 @@ To allow both left-click and right-click, use ``MOUSE_BUTTON_MASK_LEFT | MOUSE_B If ``true``, the button's state is pressed. Means the button is pressed down or toggled (if :ref:`toggle_mode` is active). Only works if :ref:`toggle_mode` is ``true``. -\ **Note:** Setting :ref:`button_pressed` will result in :ref:`toggled` to be emitted. If you want to change the pressed state without emitting that signal, use :ref:`set_pressed_no_signal`. +\ **Note:** Changing the value of :ref:`button_pressed` will result in :ref:`toggled` to be emitted. If you want to change the pressed state without emitting that signal, use :ref:`set_pressed_no_signal()`. .. rst-class:: classref-item-separator @@ -298,7 +298,7 @@ If ``true``, the button's state is pressed. Means the button is pressed down or .. rst-class:: classref-property -:ref:`bool` **disabled** = ``false`` +:ref:`bool` **disabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -307,6 +307,8 @@ If ``true``, the button's state is pressed. Means the button is pressed down or If ``true``, the button is in disabled state and can't be clicked or toggled. +\ **Note:** If the button is disabled while held down, :ref:`button_up` will be emitted. + .. rst-class:: classref-item-separator ---- @@ -315,7 +317,7 @@ If ``true``, the button is in disabled state and can't be clicked or toggled. .. rst-class:: classref-property -:ref:`bool` **keep_pressed_outside** = ``false`` +:ref:`bool` **keep_pressed_outside** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -334,7 +336,7 @@ If ``true``, the button stays pressed when moving the cursor outside the button .. rst-class:: classref-property -:ref:`Shortcut` **shortcut** +:ref:`Shortcut` **shortcut** :ref:`🔗` .. rst-class:: classref-property-setget @@ -351,7 +353,7 @@ If ``true``, the button stays pressed when moving the cursor outside the button .. rst-class:: classref-property -:ref:`bool` **shortcut_feedback** = ``true`` +:ref:`bool` **shortcut_feedback** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -368,7 +370,7 @@ If ``true``, the button will highlight for a short amount of time when its short .. rst-class:: classref-property -:ref:`bool` **shortcut_in_tooltip** = ``true`` +:ref:`bool` **shortcut_in_tooltip** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -377,6 +379,8 @@ If ``true``, the button will highlight for a short amount of time when its short If ``true``, the button will add information about its shortcut in the tooltip. +\ **Note:** This property does nothing when the tooltip control is customized using :ref:`Control._make_custom_tooltip()`. + .. rst-class:: classref-item-separator ---- @@ -385,7 +389,7 @@ If ``true``, the button will add information about its shortcut in the tooltip. .. rst-class:: classref-property -:ref:`bool` **toggle_mode** = ``false`` +:ref:`bool` **toggle_mode** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -407,9 +411,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **_pressed**\ (\ ) |virtual| +|void| **_pressed**\ (\ ) |virtual| :ref:`🔗` -Called when the button is pressed. If you need to know the button's pressed state (and :ref:`toggle_mode` is active), use :ref:`_toggled` instead. +Called when the button is pressed. If you need to know the button's pressed state (and :ref:`toggle_mode` is active), use :ref:`_toggled()` instead. .. rst-class:: classref-item-separator @@ -419,7 +423,7 @@ Called when the button is pressed. If you need to know the button's pressed stat .. rst-class:: classref-method -|void| **_toggled**\ (\ toggled_on\: :ref:`bool`\ ) |virtual| +|void| **_toggled**\ (\ toggled_on\: :ref:`bool`\ ) |virtual| :ref:`🔗` Called when the button is toggled (only if :ref:`toggle_mode` is active). @@ -431,7 +435,7 @@ Called when the button is toggled (only if :ref:`toggle_mode` **get_draw_mode**\ (\ ) |const| +:ref:`DrawMode` **get_draw_mode**\ (\ ) |const| :ref:`🔗` Returns the visual state used to draw the button. This is useful mainly when implementing your own draw code by either overriding _draw() or connecting to "draw" signal. The visual state of the button is defined by the :ref:`DrawMode` enum. @@ -443,7 +447,7 @@ Returns the visual state used to draw the button. This is useful mainly when imp .. rst-class:: classref-method -:ref:`bool` **is_hovered**\ (\ ) |const| +:ref:`bool` **is_hovered**\ (\ ) |const| :ref:`🔗` Returns ``true`` if the mouse has entered the button and has not left it yet. @@ -455,13 +459,14 @@ Returns ``true`` if the mouse has entered the button and has not left it yet. .. rst-class:: classref-method -|void| **set_pressed_no_signal**\ (\ pressed\: :ref:`bool`\ ) +|void| **set_pressed_no_signal**\ (\ pressed\: :ref:`bool`\ ) :ref:`🔗` Changes the :ref:`button_pressed` state of the button, without emitting :ref:`toggled`. Use when you just want to change the state of the button without sending the pressed event (e.g. when initializing scene). Only works if :ref:`toggle_mode` is ``true``. \ **Note:** This method doesn't unpress other buttons in :ref:`button_group`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index 0d7b202d598..3e96976fe19 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -77,6 +77,10 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`Texture2D` | :ref:`backlight_texture` | | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`bent_normal_enabled` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`bent_normal_texture` | | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`billboard_keep_scale` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`BillboardMode` | :ref:`billboard_mode` | ``0`` | @@ -95,6 +99,8 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`DepthDrawMode` | :ref:`depth_draw_mode` | ``0`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`DepthTest` | :ref:`depth_test` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`Texture2D` | :ref:`detail_albedo` | | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`BlendMode` | :ref:`detail_blend_mode` | ``0`` | @@ -115,6 +121,8 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`disable_receive_shadows` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disable_specular_occlusion` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`float` | :ref:`distance_fade_max_distance` | ``10.0`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`float` | :ref:`distance_fade_min_distance` | ``0.0`` | @@ -137,6 +145,8 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`fixed_size` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`fov_override` | ``75.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`grow` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`float` | :ref:`grow_amount` | ``0.0`` | @@ -221,6 +231,18 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`SpecularMode` | :ref:`specular_mode` | ``0`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`stencil_color` | ``Color(0, 0, 0, 1)`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`StencilCompare` | :ref:`stencil_compare` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`stencil_flags` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`StencilMode` | :ref:`stencil_mode` | ``0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`stencil_outline_thickness` | ``0.01`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`stencil_reference` | ``1`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`subsurf_scatter_enabled` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`subsurf_scatter_skin_mode` | ``false`` | @@ -245,10 +267,14 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`Transparency` | :ref:`transparency` | ``0`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_fov_override` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`use_particle_trails` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`use_point_size` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`use_z_clip_scale` | ``false`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`Vector3` | :ref:`uv1_offset` | ``Vector3(0, 0, 0)`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`Vector3` | :ref:`uv1_scale` | ``Vector3(1, 1, 1)`` | @@ -273,6 +299,8 @@ Properties +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`vertex_color_use_as_albedo` | ``false`` | +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`float` | :ref:`z_clip_scale` | ``1.0`` | + +-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+-----------------------+ .. rst-class:: classref-reftable-group @@ -309,7 +337,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **TextureParam**: +enum **TextureParam**: :ref:`🔗` .. _class_BaseMaterial3D_constant_TEXTURE_ALBEDO: @@ -351,6 +379,14 @@ Texture specifying per-pixel emission color. Texture specifying per-pixel normal vector. +.. _class_BaseMaterial3D_constant_TEXTURE_BENT_NORMAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`TextureParam` **TEXTURE_BENT_NORMAL** = ``18`` + +Texture specifying per-pixel bent normal vector. + .. _class_BaseMaterial3D_constant_TEXTURE_RIM: .. rst-class:: classref-enumeration-constant @@ -459,7 +495,7 @@ Texture holding ambient occlusion, roughness, and metallic. .. rst-class:: classref-enumeration-constant -:ref:`TextureParam` **TEXTURE_MAX** = ``18`` +:ref:`TextureParam` **TEXTURE_MAX** = ``19`` Represents the size of the :ref:`TextureParam` enum. @@ -471,7 +507,7 @@ Represents the size of the :ref:`TextureParam` .. rst-class:: classref-enumeration -enum **TextureFilter**: +enum **TextureFilter**: :ref:`🔗` .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST: @@ -537,7 +573,7 @@ Represents the size of the :ref:`TextureFilter` .. _class_BaseMaterial3D_constant_DETAIL_UV_1: @@ -563,7 +599,7 @@ Use ``UV2`` with the detail texture. .. rst-class:: classref-enumeration -enum **Transparency**: +enum **Transparency**: :ref:`🔗` .. _class_BaseMaterial3D_constant_TRANSPARENCY_DISABLED: @@ -621,7 +657,7 @@ Represents the size of the :ref:`Transparency` .. rst-class:: classref-enumeration -enum **ShadingMode**: +enum **ShadingMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_SHADING_MODE_UNSHADED: @@ -645,7 +681,7 @@ The object will be shaded per pixel. Useful for realistic shading effects. :ref:`ShadingMode` **SHADING_MODE_PER_VERTEX** = ``2`` -The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like :ref:`SHADING_MODE_PER_PIXEL`). +The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. .. _class_BaseMaterial3D_constant_SHADING_MODE_MAX: @@ -663,7 +699,7 @@ Represents the size of the :ref:`ShadingMode` e .. rst-class:: classref-enumeration -enum **Feature**: +enum **Feature**: :ref:`🔗` .. _class_BaseMaterial3D_constant_FEATURE_EMISSION: @@ -761,11 +797,19 @@ Constant for setting :ref:`refraction_enabled`. +.. _class_BaseMaterial3D_constant_FEATURE_BENT_NORMAL_MAPPING: + +.. rst-class:: classref-enumeration-constant + +:ref:`Feature` **FEATURE_BENT_NORMAL_MAPPING** = ``12`` + +Constant for setting :ref:`bent_normal_enabled`. + .. _class_BaseMaterial3D_constant_FEATURE_MAX: .. rst-class:: classref-enumeration-constant -:ref:`Feature` **FEATURE_MAX** = ``12`` +:ref:`Feature` **FEATURE_MAX** = ``13`` Represents the size of the :ref:`Feature` enum. @@ -777,7 +821,7 @@ Represents the size of the :ref:`Feature` enum. .. rst-class:: classref-enumeration -enum **BlendMode**: +enum **BlendMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_BLEND_MODE_MIX: @@ -811,6 +855,14 @@ The color of the object is subtracted from the background. The color of the object is multiplied by the background. +.. _class_BaseMaterial3D_constant_BLEND_MODE_PREMULT_ALPHA: + +.. rst-class:: classref-enumeration-constant + +:ref:`BlendMode` **BLEND_MODE_PREMULT_ALPHA** = ``4`` + +The color of the object is added to the background and the alpha channel is used to mask out the background. This is effectively a hybrid of the blend mix and add modes, useful for effects like fire where you want the flame to add but the smoke to mix. By default, this works with unshaded materials using premultiplied textures. For shaded materials, use the ``PREMUL_ALPHA_FACTOR`` built-in so that lighting can be modulated as well. + .. rst-class:: classref-item-separator ---- @@ -819,7 +871,7 @@ The color of the object is multiplied by the background. .. rst-class:: classref-enumeration -enum **AlphaAntiAliasing**: +enum **AlphaAntiAliasing**: :ref:`🔗` .. _class_BaseMaterial3D_constant_ALPHA_ANTIALIASING_OFF: @@ -853,7 +905,7 @@ Enables AlphaToCoverage and forces all non-zero alpha values to ``1``. Alpha val .. rst-class:: classref-enumeration -enum **DepthDrawMode**: +enum **DepthDrawMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_DEPTH_DRAW_OPAQUE_ONLY: @@ -885,11 +937,37 @@ Objects will not write their depth to the depth buffer, even during the depth pr ---- +.. _enum_BaseMaterial3D_DepthTest: + +.. rst-class:: classref-enumeration + +enum **DepthTest**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_DEPTH_TEST_DEFAULT: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthTest` **DEPTH_TEST_DEFAULT** = ``0`` + +Depth test will discard the pixel if it is behind other pixels. + +.. _class_BaseMaterial3D_constant_DEPTH_TEST_INVERTED: + +.. rst-class:: classref-enumeration-constant + +:ref:`DepthTest` **DEPTH_TEST_INVERTED** = ``1`` + +Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects. + +.. rst-class:: classref-item-separator + +---- + .. _enum_BaseMaterial3D_CullMode: .. rst-class:: classref-enumeration -enum **CullMode**: +enum **CullMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_CULL_BACK: @@ -923,7 +1001,7 @@ No face culling is performed; both the front face and back face will be visible. .. rst-class:: classref-enumeration -enum **Flags**: +enum **Flags**: :ref:`🔗` .. _class_BaseMaterial3D_constant_FLAG_DISABLE_DEPTH_TEST: @@ -1103,11 +1181,35 @@ Enables multichannel signed distance field rendering shader. Disables receiving depth-based or volumetric fog. +.. _class_BaseMaterial3D_constant_FLAG_DISABLE_SPECULAR_OCCLUSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_DISABLE_SPECULAR_OCCLUSION** = ``22`` + +Disables specular occlusion. + +.. _class_BaseMaterial3D_constant_FLAG_USE_Z_CLIP_SCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_Z_CLIP_SCALE** = ``23`` + +Enables using :ref:`z_clip_scale`. + +.. _class_BaseMaterial3D_constant_FLAG_USE_FOV_OVERRIDE: + +.. rst-class:: classref-enumeration-constant + +:ref:`Flags` **FLAG_USE_FOV_OVERRIDE** = ``24`` + +Enables using :ref:`fov_override`. + .. _class_BaseMaterial3D_constant_FLAG_MAX: .. rst-class:: classref-enumeration-constant -:ref:`Flags` **FLAG_MAX** = ``22`` +:ref:`Flags` **FLAG_MAX** = ``25`` Represents the size of the :ref:`Flags` enum. @@ -1119,7 +1221,7 @@ Represents the size of the :ref:`Flags` enum. .. rst-class:: classref-enumeration -enum **DiffuseMode**: +enum **DiffuseMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_DIFFUSE_BURLEY: @@ -1161,7 +1263,7 @@ Uses a hard cut for lighting, with smoothing affected by roughness. .. rst-class:: classref-enumeration -enum **SpecularMode**: +enum **SpecularMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_SPECULAR_SCHLICK_GGX: @@ -1171,6 +1273,10 @@ enum **SpecularMode**: Default specular blob. +\ **Note:** Forward+ uses multiscattering for more accurate reflections, although the impact of multiscattering is more noticeable on rough metallic surfaces than on smooth, non-metallic surfaces. + +\ **Note:** Mobile and Compatibility don't perform multiscattering for performance reasons. Instead, they perform single scattering, which means rough metallic surfaces may look slightly darker than intended. + .. _class_BaseMaterial3D_constant_SPECULAR_TOON: .. rst-class:: classref-enumeration-constant @@ -1195,7 +1301,7 @@ No specular blob. This is slightly faster to render than other specular modes. .. rst-class:: classref-enumeration -enum **BillboardMode**: +enum **BillboardMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_BILLBOARD_DISABLED: @@ -1239,7 +1345,7 @@ The :ref:`ParticleProcessMaterial.anim_speed_min` .. _class_BaseMaterial3D_constant_TEXTURE_CHANNEL_RED: @@ -1289,7 +1395,7 @@ Used to read from the linear (non-perceptual) average of the red, green and blue .. rst-class:: classref-enumeration -enum **EmissionOperator**: +enum **EmissionOperator**: :ref:`🔗` .. _class_BaseMaterial3D_constant_EMISSION_OP_ADD: @@ -1315,7 +1421,7 @@ Multiplies the emission color by the color from the emission texture. .. rst-class:: classref-enumeration -enum **DistanceFadeMode**: +enum **DistanceFadeMode**: :ref:`🔗` .. _class_BaseMaterial3D_constant_DISTANCE_FADE_DISABLED: @@ -1349,6 +1455,152 @@ Smoothly fades the object out based on each pixel's distance from the camera usi Smoothly fades the object out based on the object's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than :ref:`DISTANCE_FADE_PIXEL_ALPHA` and :ref:`DISTANCE_FADE_PIXEL_DITHER`. +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_StencilMode: + +.. rst-class:: classref-enumeration + +enum **StencilMode**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_DISABLED** = ``0`` + +Disables stencil operations. + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_OUTLINE: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_OUTLINE** = ``1`` + +Stencil preset which applies an outline to the object. + +\ **Note:** Requires a :ref:`Material.next_pass` material which will be automatically applied. Any manual changes made to :ref:`Material.next_pass` will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a :ref:`Material.next_pass` material on a material that uses stencil presets, use :ref:`GeometryInstance3D.material_overlay` instead. + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_XRAY: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_XRAY** = ``2`` + +Stencil preset which shows a silhouette of the object behind walls. + +\ **Note:** Requires a :ref:`Material.next_pass` material which will be automatically applied. Any manual changes made to :ref:`Material.next_pass` will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a :ref:`Material.next_pass` material on a material that uses stencil presets, use :ref:`GeometryInstance3D.material_overlay` instead. + +.. _class_BaseMaterial3D_constant_STENCIL_MODE_CUSTOM: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilMode` **STENCIL_MODE_CUSTOM** = ``3`` + +Enables stencil operations without a preset. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_StencilFlags: + +.. rst-class:: classref-enumeration + +enum **StencilFlags**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_STENCIL_FLAG_READ: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilFlags` **STENCIL_FLAG_READ** = ``1`` + +The material will only be rendered where it passes a stencil comparison with existing stencil buffer values. See :ref:`StencilCompare`. + +.. _class_BaseMaterial3D_constant_STENCIL_FLAG_WRITE: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilFlags` **STENCIL_FLAG_WRITE** = ``2`` + +The material will write the reference value to the stencil buffer where it passes the depth test. + +.. _class_BaseMaterial3D_constant_STENCIL_FLAG_WRITE_DEPTH_FAIL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilFlags` **STENCIL_FLAG_WRITE_DEPTH_FAIL** = ``4`` + +The material will write the reference value to the stencil buffer where it fails the depth test. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_BaseMaterial3D_StencilCompare: + +.. rst-class:: classref-enumeration + +enum **StencilCompare**: :ref:`🔗` + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_ALWAYS: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_ALWAYS** = ``0`` + +Always passes the stencil test. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_LESS: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_LESS** = ``1`` + +Passes the stencil test when the reference value is less than the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_EQUAL** = ``2`` + +Passes the stencil test when the reference value is equal to the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_LESS_OR_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_LESS_OR_EQUAL** = ``3`` + +Passes the stencil test when the reference value is less than or equal to the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_GREATER: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_GREATER** = ``4`` + +Passes the stencil test when the reference value is greater than the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_NOT_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_NOT_EQUAL** = ``5`` + +Passes the stencil test when the reference value is not equal to the existing stencil value. + +.. _class_BaseMaterial3D_constant_STENCIL_COMPARE_GREATER_OR_EQUAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`StencilCompare` **STENCIL_COMPARE_GREATER_OR_EQUAL** = ``6`` + +Passes the stencil test when the reference value is greater than or equal to the existing stencil value. + .. rst-class:: classref-section-separator ---- @@ -1362,7 +1614,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Color` **albedo_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **albedo_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1381,7 +1633,7 @@ The material's base color. .. rst-class:: classref-property -:ref:`Texture2D` **albedo_texture** +:ref:`Texture2D` **albedo_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1400,7 +1652,7 @@ If the texture appears unexpectedly too dark or too bright, check :ref:`albedo_t .. rst-class:: classref-property -:ref:`bool` **albedo_texture_force_srgb** = ``false`` +:ref:`bool` **albedo_texture_force_srgb** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1419,7 +1671,7 @@ This should only be enabled when needed (typically when using a :ref:`ViewportTe .. rst-class:: classref-property -:ref:`bool` **albedo_texture_msdf** = ``false`` +:ref:`bool` **albedo_texture_msdf** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1436,7 +1688,7 @@ Enables multichannel signed distance field rendering shader. Use :ref:`msdf_pixe .. rst-class:: classref-property -:ref:`float` **alpha_antialiasing_edge** +:ref:`float` **alpha_antialiasing_edge** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1453,14 +1705,14 @@ Threshold at which antialiasing will be applied on the alpha channel. .. rst-class:: classref-property -:ref:`AlphaAntiAliasing` **alpha_antialiasing_mode** +:ref:`AlphaAntiAliasing` **alpha_antialiasing_mode** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_alpha_antialiasing**\ (\ value\: :ref:`AlphaAntiAliasing`\ ) - :ref:`AlphaAntiAliasing` **get_alpha_antialiasing**\ (\ ) -The type of alpha antialiasing to apply. See :ref:`AlphaAntiAliasing`. +The type of alpha antialiasing to apply. .. rst-class:: classref-item-separator @@ -1470,7 +1722,7 @@ The type of alpha antialiasing to apply. See :ref:`AlphaAntiAliasing` **alpha_hash_scale** +:ref:`float` **alpha_hash_scale** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1487,7 +1739,7 @@ The hashing scale for Alpha Hash. Recommended values between ``0`` and ``2``. .. rst-class:: classref-property -:ref:`float` **alpha_scissor_threshold** +:ref:`float` **alpha_scissor_threshold** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1504,7 +1756,7 @@ Threshold at which the alpha scissor will discard values. Higher values will res .. rst-class:: classref-property -:ref:`float` **anisotropy** = ``0.0`` +:ref:`float` **anisotropy** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1521,14 +1773,14 @@ The strength of the anisotropy effect. This is multiplied by :ref:`anisotropy_fl .. rst-class:: classref-property -:ref:`bool` **anisotropy_enabled** = ``false`` +:ref:`bool` **anisotropy_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) - :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminium and hair reflections. +If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminum and hair reflections. \ **Note:** Mesh tangents are needed for anisotropy to work. If the mesh does not contain tangents, the anisotropy effect will appear broken. @@ -1542,7 +1794,7 @@ If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular .. rst-class:: classref-property -:ref:`Texture2D` **anisotropy_flowmap** +:ref:`Texture2D` **anisotropy_flowmap** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1561,7 +1813,7 @@ If present, the texture's alpha channel will be used to multiply the strength of .. rst-class:: classref-property -:ref:`bool` **ao_enabled** = ``false`` +:ref:`bool` **ao_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1578,7 +1830,7 @@ If ``true``, ambient occlusion is enabled. Ambient occlusion darkens areas based .. rst-class:: classref-property -:ref:`float` **ao_light_affect** = ``0.0`` +:ref:`float` **ao_light_affect** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1595,7 +1847,7 @@ Amount that ambient occlusion affects lighting from lights. If ``0``, ambient oc .. rst-class:: classref-property -:ref:`bool` **ao_on_uv2** = ``false`` +:ref:`bool` **ao_on_uv2** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1612,7 +1864,7 @@ If ``true``, use ``UV2`` coordinates to look up from the :ref:`ao_texture` **ao_texture** +:ref:`Texture2D` **ao_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1629,7 +1881,7 @@ Texture that defines the amount of ambient occlusion for a given point on the ob .. rst-class:: classref-property -:ref:`TextureChannel` **ao_texture_channel** = ``0`` +:ref:`TextureChannel` **ao_texture_channel** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1646,7 +1898,7 @@ Specifies the channel of the :ref:`ao_texture` **backlight** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **backlight** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1663,7 +1915,7 @@ The color used by the backlight effect. Represents the light passing through an .. rst-class:: classref-property -:ref:`bool` **backlight_enabled** = ``false`` +:ref:`bool` **backlight_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1680,7 +1932,7 @@ If ``true``, the backlight effect is enabled. See also :ref:`subsurf_scatter_tra .. rst-class:: classref-property -:ref:`Texture2D` **backlight_texture** +:ref:`Texture2D` **backlight_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1693,11 +1945,51 @@ Texture used to control the backlight effect per-pixel. Added to :ref:`backlight ---- +.. _class_BaseMaterial3D_property_bent_normal_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **bent_normal_enabled** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| + +If ``true``, the bent normal map is enabled. This allows for more accurate indirect lighting and specular occlusion. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_bent_normal_texture: + +.. rst-class:: classref-property + +:ref:`Texture2D` **bent_normal_texture** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +- :ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| + +Texture that specifies the average direction of incoming ambient light at a given pixel. The :ref:`bent_normal_texture` only uses the red and green channels; the blue and alpha channels are ignored. The normal read from :ref:`bent_normal_texture` is oriented around the surface normal provided by the :ref:`Mesh`. + +\ **Note:** A bent normal map is different from a regular normal map. When baking a bent normal map make sure to use **a cosine distribution** for the bent normal map to work correctly. + +\ **Note:** The mesh must have both normals and tangents defined in its vertex data. Otherwise, the shading produced by the bent normal map will not look correct. If creating geometry with :ref:`SurfaceTool`, you can use :ref:`SurfaceTool.generate_normals()` and :ref:`SurfaceTool.generate_tangents()` to automatically generate normals and tangents respectively. + +\ **Note:** Godot expects the bent normal map to use X+, Y+, and Z+ coordinates. See `this page `__ for a comparison of normal map coordinates expected by popular engines. + +.. rst-class:: classref-item-separator + +---- + .. _class_BaseMaterial3D_property_billboard_keep_scale: .. rst-class:: classref-property -:ref:`bool` **billboard_keep_scale** = ``false`` +:ref:`bool` **billboard_keep_scale** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1714,16 +2006,14 @@ If ``true``, the shader will keep the scale set for the mesh. Otherwise, the sca .. rst-class:: classref-property -:ref:`BillboardMode` **billboard_mode** = ``0`` +:ref:`BillboardMode` **billboard_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_billboard_mode**\ (\ value\: :ref:`BillboardMode`\ ) - :ref:`BillboardMode` **get_billboard_mode**\ (\ ) -Controls how the object faces the camera. See :ref:`BillboardMode`. - -\ **Note:** When billboarding is enabled and the material also casts shadows, billboards will face **the** camera in the scene when rendering shadows. In scenes with multiple cameras, the intended shadow cannot be determined and this will result in undefined behavior. See `GitHub Pull Request #72638 `__ for details. +Controls how the object faces the camera. \ **Note:** Billboard mode is not suitable for VR because the left-right vector of the camera is not horizontal when the screen is attached to your head instead of on the table. See `GitHub issue #41567 `__ for details. @@ -1735,7 +2025,7 @@ Controls how the object faces the camera. See :ref:`BillboardMode` **blend_mode** = ``0`` +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1744,7 +2034,7 @@ Controls how the object faces the camera. See :ref:`BillboardMode`. +\ **Note:** Values other than ``Mix`` force the object into the transparent pipeline. .. rst-class:: classref-item-separator @@ -1754,7 +2044,7 @@ The material's blend mode. .. rst-class:: classref-property -:ref:`float` **clearcoat** = ``1.0`` +:ref:`float` **clearcoat** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1771,7 +2061,7 @@ Sets the strength of the clearcoat effect. Setting to ``0`` looks the same as di .. rst-class:: classref-property -:ref:`bool` **clearcoat_enabled** = ``false`` +:ref:`bool` **clearcoat_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1790,7 +2080,7 @@ If ``true``, clearcoat rendering is enabled. Adds a secondary transparent pass t .. rst-class:: classref-property -:ref:`float` **clearcoat_roughness** = ``0.5`` +:ref:`float` **clearcoat_roughness** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1807,7 +2097,7 @@ Sets the roughness of the clearcoat pass. A higher value results in a rougher cl .. rst-class:: classref-property -:ref:`Texture2D` **clearcoat_texture** +:ref:`Texture2D` **clearcoat_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1824,14 +2114,14 @@ Texture that defines the strength of the clearcoat effect and the glossiness of .. rst-class:: classref-property -:ref:`CullMode` **cull_mode** = ``0`` +:ref:`CullMode` **cull_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_cull_mode**\ (\ value\: :ref:`CullMode`\ ) - :ref:`CullMode` **get_cull_mode**\ (\ ) -Determines which side of the triangle to cull depending on whether the triangle faces towards or away from the camera. See :ref:`CullMode`. +Determines which side of the triangle to cull depending on whether the triangle faces towards or away from the camera. .. rst-class:: classref-item-separator @@ -1841,14 +2131,35 @@ Determines which side of the triangle to cull depending on whether the triangle .. rst-class:: classref-property -:ref:`DepthDrawMode` **depth_draw_mode** = ``0`` +:ref:`DepthDrawMode` **depth_draw_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_depth_draw_mode**\ (\ value\: :ref:`DepthDrawMode`\ ) - :ref:`DepthDrawMode` **get_depth_draw_mode**\ (\ ) -Determines when depth rendering takes place. See :ref:`DepthDrawMode`. See also :ref:`transparency`. +Determines when depth rendering takes place. See also :ref:`transparency`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_depth_test: + +.. rst-class:: classref-property + +:ref:`DepthTest` **depth_test** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_depth_test**\ (\ value\: :ref:`DepthTest`\ ) +- :ref:`DepthTest` **get_depth_test**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +Determines which comparison operator is used when testing depth. See :ref:`DepthTest`. + +\ **Note:** Changing :ref:`depth_test` to a non-default value only has a visible effect when used on a transparent material, or a material that has :ref:`depth_draw_mode` set to :ref:`DEPTH_DRAW_DISABLED`. .. rst-class:: classref-item-separator @@ -1858,7 +2169,7 @@ Determines when depth rendering takes place. See :ref:`DepthDrawMode` **detail_albedo** +:ref:`Texture2D` **detail_albedo** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1877,14 +2188,14 @@ Texture that specifies the color of the detail overlay. :ref:`detail_albedo` **detail_blend_mode** = ``0`` +:ref:`BlendMode` **detail_blend_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_detail_blend_mode**\ (\ value\: :ref:`BlendMode`\ ) - :ref:`BlendMode` **get_detail_blend_mode**\ (\ ) -Specifies how the :ref:`detail_albedo` should blend with the current ``ALBEDO``. See :ref:`BlendMode` for options. +Specifies how the :ref:`detail_albedo` should blend with the current ``ALBEDO``. .. rst-class:: classref-item-separator @@ -1894,7 +2205,7 @@ Specifies how the :ref:`detail_albedo` **detail_enabled** = ``false`` +:ref:`bool` **detail_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1911,7 +2222,7 @@ If ``true``, enables the detail overlay. Detail is a second texture that gets mi .. rst-class:: classref-property -:ref:`Texture2D` **detail_mask** +:ref:`Texture2D` **detail_mask** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1928,7 +2239,7 @@ Texture used to specify how the detail textures get blended with the base textur .. rst-class:: classref-property -:ref:`Texture2D` **detail_normal** +:ref:`Texture2D` **detail_normal** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1947,14 +2258,14 @@ Texture that specifies the per-pixel normal of the detail overlay. The :ref:`det .. rst-class:: classref-property -:ref:`DetailUV` **detail_uv_layer** = ``0`` +:ref:`DetailUV` **detail_uv_layer** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_detail_uv**\ (\ value\: :ref:`DetailUV`\ ) - :ref:`DetailUV` **get_detail_uv**\ (\ ) -Specifies whether to use ``UV`` or ``UV2`` for the detail layer. See :ref:`DetailUV` for options. +Specifies whether to use ``UV`` or ``UV2`` for the detail layer. .. rst-class:: classref-item-separator @@ -1964,14 +2275,14 @@ Specifies whether to use ``UV`` or ``UV2`` for the detail layer. See :ref:`Detai .. rst-class:: classref-property -:ref:`DiffuseMode` **diffuse_mode** = ``0`` +:ref:`DiffuseMode` **diffuse_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_diffuse_mode**\ (\ value\: :ref:`DiffuseMode`\ ) - :ref:`DiffuseMode` **get_diffuse_mode**\ (\ ) -The algorithm used for diffuse light scattering. See :ref:`DiffuseMode`. +The algorithm used for diffuse light scattering. .. rst-class:: classref-item-separator @@ -1981,7 +2292,7 @@ The algorithm used for diffuse light scattering. See :ref:`DiffuseMode` **disable_ambient_light** = ``false`` +:ref:`bool` **disable_ambient_light** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1998,7 +2309,7 @@ If ``true``, the object receives no ambient light. .. rst-class:: classref-property -:ref:`bool` **disable_fog** = ``false`` +:ref:`bool` **disable_fog** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2015,7 +2326,7 @@ If ``true``, the object will not be affected by fog (neither volumetric nor dept .. rst-class:: classref-property -:ref:`bool` **disable_receive_shadows** = ``false`` +:ref:`bool` **disable_receive_shadows** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2028,11 +2339,28 @@ If ``true``, the object receives no shadow that would otherwise be cast onto it. ---- +.. _class_BaseMaterial3D_property_disable_specular_occlusion: + +.. rst-class:: classref-property + +:ref:`bool` **disable_specular_occlusion** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true``, disables specular occlusion even if :ref:`ProjectSettings.rendering/reflections/specular_occlusion/enabled` is ``false``. + +.. rst-class:: classref-item-separator + +---- + .. _class_BaseMaterial3D_property_distance_fade_max_distance: .. rst-class:: classref-property -:ref:`float` **distance_fade_max_distance** = ``10.0`` +:ref:`float` **distance_fade_max_distance** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2051,7 +2379,7 @@ Distance at which the object appears fully opaque. .. rst-class:: classref-property -:ref:`float` **distance_fade_min_distance** = ``0.0`` +:ref:`float` **distance_fade_min_distance** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2070,7 +2398,7 @@ Distance at which the object starts to become visible. If the object is less tha .. rst-class:: classref-property -:ref:`DistanceFadeMode` **distance_fade_mode** = ``0`` +:ref:`DistanceFadeMode` **distance_fade_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2087,7 +2415,7 @@ Specifies which type of fade to use. Can be any of the :ref:`DistanceFadeMode` **emission** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **emission** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2104,7 +2432,7 @@ The emitted light's color. See :ref:`emission_enabled` **emission_enabled** = ``false`` +:ref:`bool` **emission_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2121,7 +2449,7 @@ If ``true``, the body emits light. Emitting light makes the object appear bright .. rst-class:: classref-property -:ref:`float` **emission_energy_multiplier** = ``1.0`` +:ref:`float` **emission_energy_multiplier** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2138,7 +2466,7 @@ Multiplier for emitted light. See :ref:`emission_enabled` **emission_intensity** +:ref:`float` **emission_intensity** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2155,7 +2483,7 @@ Luminance of emitted light, measured in nits (candela per square meter). Only av .. rst-class:: classref-property -:ref:`bool` **emission_on_uv2** = ``false`` +:ref:`bool` **emission_on_uv2** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2172,14 +2500,14 @@ Use ``UV2`` to read from the :ref:`emission_texture` **emission_operator** = ``0`` +:ref:`EmissionOperator` **emission_operator** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_emission_operator**\ (\ value\: :ref:`EmissionOperator`\ ) - :ref:`EmissionOperator` **get_emission_operator**\ (\ ) -Sets how :ref:`emission` interacts with :ref:`emission_texture`. Can either add or multiply. See :ref:`EmissionOperator` for options. +Sets how :ref:`emission` interacts with :ref:`emission_texture`. Can either add or multiply. .. rst-class:: classref-item-separator @@ -2189,7 +2517,7 @@ Sets how :ref:`emission` interacts with .. rst-class:: classref-property -:ref:`Texture2D` **emission_texture** +:ref:`Texture2D` **emission_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2206,14 +2534,33 @@ Texture that specifies how much surface emits light at a given point. .. rst-class:: classref-property -:ref:`bool` **fixed_size** = ``false`` +:ref:`bool` **fixed_size** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) - :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -If ``true``, the object is rendered at the same size regardless of distance. +If ``true``, the object is rendered at the same size regardless of distance. The object's size on screen is the same as if the camera was ``1.0`` units away from the object's origin, regardless of the actual distance from the camera. The :ref:`Camera3D`'s field of view (or :ref:`Camera3D.size` when in orthogonal/frustum mode) still affects the size the object is drawn at. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_fov_override: + +.. rst-class:: classref-property + +:ref:`float` **fov_override** = ``75.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_fov_override**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_fov_override**\ (\ ) + +Overrides the :ref:`Camera3D`'s field of view angle (in degrees). + +\ **Note:** This behaves as if the field of view is set on a :ref:`Camera3D` with :ref:`Camera3D.keep_aspect` set to :ref:`Camera3D.KEEP_HEIGHT`. Additionally, it may not look correct on a non-perspective camera where the field of view setting is ignored. .. rst-class:: classref-item-separator @@ -2223,7 +2570,7 @@ If ``true``, the object is rendered at the same size regardless of distance. .. rst-class:: classref-property -:ref:`bool` **grow** = ``false`` +:ref:`bool` **grow** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2232,7 +2579,7 @@ If ``true``, the object is rendered at the same size regardless of distance. If ``true``, enables the vertex grow setting. This can be used to create mesh-based outlines using a second material pass and its :ref:`cull_mode` set to :ref:`CULL_FRONT`. See also :ref:`grow_amount`. -\ **Note:** Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using `face weighted normals `__ in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh. +\ **Note:** Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using `face weighted normals `__ in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh. .. rst-class:: classref-item-separator @@ -2242,7 +2589,7 @@ If ``true``, enables the vertex grow setting. This can be used to create mesh-ba .. rst-class:: classref-property -:ref:`float` **grow_amount** = ``0.0`` +:ref:`float` **grow_amount** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2259,7 +2606,7 @@ Grows object vertices in the direction of their normals. Only effective if :ref: .. rst-class:: classref-property -:ref:`bool` **heightmap_deep_parallax** = ``false`` +:ref:`bool` **heightmap_deep_parallax** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2276,7 +2623,7 @@ If ``true``, uses parallax occlusion mapping to represent depth in the material .. rst-class:: classref-property -:ref:`bool` **heightmap_enabled** = ``false`` +:ref:`bool` **heightmap_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2295,7 +2642,7 @@ If ``true``, height mapping is enabled (also called "parallax mapping" or "depth .. rst-class:: classref-property -:ref:`bool` **heightmap_flip_binormal** = ``false`` +:ref:`bool` **heightmap_flip_binormal** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2312,7 +2659,7 @@ If ``true``, flips the mesh's binormal vectors when interpreting the height map. .. rst-class:: classref-property -:ref:`bool` **heightmap_flip_tangent** = ``false`` +:ref:`bool` **heightmap_flip_tangent** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2329,7 +2676,7 @@ If ``true``, flips the mesh's tangent vectors when interpreting the height map. .. rst-class:: classref-property -:ref:`bool` **heightmap_flip_texture** = ``false`` +:ref:`bool` **heightmap_flip_texture** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2348,7 +2695,7 @@ This can be enabled for compatibility with some materials authored for Godot 3.x .. rst-class:: classref-property -:ref:`int` **heightmap_max_layers** +:ref:`int` **heightmap_max_layers** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2367,7 +2714,7 @@ The number of layers to use for parallax occlusion mapping when the camera is up .. rst-class:: classref-property -:ref:`int` **heightmap_min_layers** +:ref:`int` **heightmap_min_layers** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2386,7 +2733,7 @@ The number of layers to use for parallax occlusion mapping when the camera is fa .. rst-class:: classref-property -:ref:`float` **heightmap_scale** = ``5.0`` +:ref:`float` **heightmap_scale** = ``5.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2405,7 +2752,7 @@ The heightmap scale to use for the parallax effect (see :ref:`heightmap_enabled< .. rst-class:: classref-property -:ref:`Texture2D` **heightmap_texture** +:ref:`Texture2D` **heightmap_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2426,7 +2773,7 @@ For best results, the texture should be normalized (with :ref:`heightmap_scale` **metallic** = ``0.0`` +:ref:`float` **metallic** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2443,7 +2790,7 @@ A high value makes the material appear more like a metal. Non-metals use their a .. rst-class:: classref-property -:ref:`float` **metallic_specular** = ``0.5`` +:ref:`float` **metallic_specular** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2462,7 +2809,7 @@ Adjusts the strength of specular reflections. Specular reflections are composed .. rst-class:: classref-property -:ref:`Texture2D` **metallic_texture** +:ref:`Texture2D` **metallic_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2479,7 +2826,7 @@ Texture used to specify metallic for an object. This is multiplied by :ref:`meta .. rst-class:: classref-property -:ref:`TextureChannel` **metallic_texture_channel** = ``0`` +:ref:`TextureChannel` **metallic_texture_channel** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2496,7 +2843,7 @@ Specifies the channel of the :ref:`metallic_texture` **msdf_outline_size** = ``0.0`` +:ref:`float` **msdf_outline_size** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2513,7 +2860,7 @@ The width of the shape outline. .. rst-class:: classref-property -:ref:`float` **msdf_pixel_range** = ``4.0`` +:ref:`float` **msdf_pixel_range** = ``4.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2530,7 +2877,7 @@ The width of the range around the shape between the minimum and maximum represen .. rst-class:: classref-property -:ref:`bool` **no_depth_test** = ``false`` +:ref:`bool` **no_depth_test** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2547,7 +2894,7 @@ If ``true``, depth testing is disabled and the object will be drawn in render or .. rst-class:: classref-property -:ref:`bool` **normal_enabled** = ``false`` +:ref:`bool` **normal_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2564,7 +2911,7 @@ If ``true``, normal mapping is enabled. This has a slight performance cost, espe .. rst-class:: classref-property -:ref:`float` **normal_scale** = ``1.0`` +:ref:`float` **normal_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2581,7 +2928,7 @@ The strength of the normal map's effect. .. rst-class:: classref-property -:ref:`Texture2D` **normal_texture** +:ref:`Texture2D` **normal_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2590,7 +2937,7 @@ The strength of the normal map's effect. Texture used to specify the normal at a given pixel. The :ref:`normal_texture` only uses the red and green channels; the blue and alpha channels are ignored. The normal read from :ref:`normal_texture` is oriented around the surface normal provided by the :ref:`Mesh`. -\ **Note:** The mesh must have both normals and tangents defined in its vertex data. Otherwise, the normal map won't render correctly and will only appear to darken the whole surface. If creating geometry with :ref:`SurfaceTool`, you can use :ref:`SurfaceTool.generate_normals` and :ref:`SurfaceTool.generate_tangents` to automatically generate normals and tangents respectively. +\ **Note:** The mesh must have both normals and tangents defined in its vertex data. Otherwise, the normal map won't render correctly and will only appear to darken the whole surface. If creating geometry with :ref:`SurfaceTool`, you can use :ref:`SurfaceTool.generate_normals()` and :ref:`SurfaceTool.generate_tangents()` to automatically generate normals and tangents respectively. \ **Note:** Godot expects the normal map to use X+, Y+, and Z+ coordinates. See `this page `__ for a comparison of normal map coordinates expected by popular engines. @@ -2604,7 +2951,7 @@ Texture used to specify the normal at a given pixel. The :ref:`normal_texture` **orm_texture** +:ref:`Texture2D` **orm_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2621,7 +2968,7 @@ The Occlusion/Roughness/Metallic texture to use. This is a more efficient replac .. rst-class:: classref-property -:ref:`int` **particles_anim_h_frames** +:ref:`int` **particles_anim_h_frames** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2638,7 +2985,7 @@ The number of horizontal frames in the particle sprite sheet. Only enabled when .. rst-class:: classref-property -:ref:`bool` **particles_anim_loop** +:ref:`bool` **particles_anim_loop** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2655,7 +3002,7 @@ If ``true``, particle animations are looped. Only enabled when using :ref:`BILLB .. rst-class:: classref-property -:ref:`int` **particles_anim_v_frames** +:ref:`int` **particles_anim_v_frames** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2672,7 +3019,7 @@ The number of vertical frames in the particle sprite sheet. Only enabled when us .. rst-class:: classref-property -:ref:`float` **point_size** = ``1.0`` +:ref:`float` **point_size** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2689,7 +3036,7 @@ The point size in pixels. See :ref:`use_point_size` **proximity_fade_distance** = ``1.0`` +:ref:`float` **proximity_fade_distance** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2706,7 +3053,7 @@ Distance over which the fade effect takes place. The larger the distance the lon .. rst-class:: classref-property -:ref:`bool` **proximity_fade_enabled** = ``false`` +:ref:`bool` **proximity_fade_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2723,7 +3070,7 @@ If ``true``, the proximity fade effect is enabled. The proximity fade effect fad .. rst-class:: classref-property -:ref:`bool` **refraction_enabled** = ``false`` +:ref:`bool` **refraction_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2732,6 +3079,8 @@ If ``true``, the proximity fade effect is enabled. The proximity fade effect fad If ``true``, the refraction effect is enabled. Distorts transparency based on light from behind the object. +\ **Note:** Refraction is implemented using the screen texture. Only opaque materials will appear in the refraction, since transparent materials do not appear in the screen texture. + .. rst-class:: classref-item-separator ---- @@ -2740,7 +3089,7 @@ If ``true``, the refraction effect is enabled. Distorts transparency based on li .. rst-class:: classref-property -:ref:`float` **refraction_scale** = ``0.05`` +:ref:`float` **refraction_scale** = ``0.05`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2757,7 +3106,7 @@ The strength of the refraction effect. .. rst-class:: classref-property -:ref:`Texture2D` **refraction_texture** +:ref:`Texture2D` **refraction_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2774,7 +3123,7 @@ Texture that controls the strength of the refraction per-pixel. Multiplied by :r .. rst-class:: classref-property -:ref:`TextureChannel` **refraction_texture_channel** = ``0`` +:ref:`TextureChannel` **refraction_texture_channel** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2791,7 +3140,7 @@ Specifies the channel of the :ref:`refraction_texture` **rim** = ``1.0`` +:ref:`float` **rim** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2808,7 +3157,7 @@ Sets the strength of the rim lighting effect. .. rst-class:: classref-property -:ref:`bool` **rim_enabled** = ``false`` +:ref:`bool` **rim_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2827,7 +3176,7 @@ If ``true``, rim effect is enabled. Rim lighting increases the brightness at gla .. rst-class:: classref-property -:ref:`Texture2D` **rim_texture** +:ref:`Texture2D` **rim_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2844,7 +3193,7 @@ Texture used to set the strength of the rim lighting effect per-pixel. Multiplie .. rst-class:: classref-property -:ref:`float` **rim_tint** = ``0.5`` +:ref:`float` **rim_tint** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2861,7 +3210,7 @@ The amount of to blend light and albedo color when rendering rim effect. If ``0` .. rst-class:: classref-property -:ref:`float` **roughness** = ``1.0`` +:ref:`float` **roughness** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2878,7 +3227,7 @@ Surface reflection. A value of ``0`` represents a perfect mirror while a value o .. rst-class:: classref-property -:ref:`Texture2D` **roughness_texture** +:ref:`Texture2D` **roughness_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -2895,7 +3244,7 @@ Texture used to control the roughness per-pixel. Multiplied by :ref:`roughness` **roughness_texture_channel** = ``0`` +:ref:`TextureChannel` **roughness_texture_channel** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2912,7 +3261,7 @@ Specifies the channel of the :ref:`roughness_texture` **shading_mode** = ``1`` +:ref:`ShadingMode` **shading_mode** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2921,8 +3270,6 @@ Specifies the channel of the :ref:`roughness_texture` **shadow_to_opacity** = ``false`` +:ref:`bool` **shadow_to_opacity** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2948,14 +3295,14 @@ If ``true``, enables the "shadow to opacity" render mode where lighting modifies .. rst-class:: classref-property -:ref:`SpecularMode` **specular_mode** = ``0`` +:ref:`SpecularMode` **specular_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_specular_mode**\ (\ value\: :ref:`SpecularMode`\ ) - :ref:`SpecularMode` **get_specular_mode**\ (\ ) -The method for rendering the specular blob. See :ref:`SpecularMode`. +The method for rendering the specular blob. \ **Note:** :ref:`specular_mode` only applies to the specular blob. It does not affect specular reflections from the sky, screen-space reflections, :ref:`VoxelGI`, SDFGI or :ref:`ReflectionProbe`\ s. To disable reflections from these sources as well, set :ref:`metallic_specular` to ``0.0`` instead. @@ -2963,11 +3310,125 @@ The method for rendering the specular blob. See :ref:`SpecularMode` **stencil_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stencil_effect_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_stencil_effect_color**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The primary color of the stencil effect. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_stencil_compare: + +.. rst-class:: classref-property + +:ref:`StencilCompare` **stencil_compare** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stencil_compare**\ (\ value\: :ref:`StencilCompare`\ ) +- :ref:`StencilCompare` **get_stencil_compare**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The comparison operator to use for stencil masking operations. See :ref:`StencilCompare`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_stencil_flags: + +.. rst-class:: classref-property + +:ref:`int` **stencil_flags** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stencil_flags**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stencil_flags**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The flags dictating how the stencil operation behaves. See :ref:`StencilFlags`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_stencil_mode: + +.. rst-class:: classref-property + +:ref:`StencilMode` **stencil_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stencil_mode**\ (\ value\: :ref:`StencilMode`\ ) +- :ref:`StencilMode` **get_stencil_mode**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The stencil effect mode. See :ref:`StencilMode`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_stencil_outline_thickness: + +.. rst-class:: classref-property + +:ref:`float` **stencil_outline_thickness** = ``0.01`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stencil_effect_outline_thickness**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_stencil_effect_outline_thickness**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The outline thickness for :ref:`STENCIL_MODE_OUTLINE`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_stencil_reference: + +.. rst-class:: classref-property + +:ref:`int` **stencil_reference** = ``1`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_stencil_reference**\ (\ value\: :ref:`int`\ ) +- :ref:`int` **get_stencil_reference**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The stencil reference value (0-255). Typically a power of 2. + +.. rst-class:: classref-item-separator + +---- + .. _class_BaseMaterial3D_property_subsurf_scatter_enabled: .. rst-class:: classref-property -:ref:`bool` **subsurf_scatter_enabled** = ``false`` +:ref:`bool` **subsurf_scatter_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -2984,7 +3445,7 @@ If ``true``, subsurface scattering is enabled. Emulates light that penetrates an .. rst-class:: classref-property -:ref:`bool` **subsurf_scatter_skin_mode** = ``false`` +:ref:`bool` **subsurf_scatter_skin_mode** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3001,7 +3462,7 @@ If ``true``, subsurface scattering will use a special mode optimized for the col .. rst-class:: classref-property -:ref:`float` **subsurf_scatter_strength** = ``0.0`` +:ref:`float` **subsurf_scatter_strength** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3018,7 +3479,7 @@ The strength of the subsurface scattering effect. The depth of the effect is als .. rst-class:: classref-property -:ref:`Texture2D` **subsurf_scatter_texture** +:ref:`Texture2D` **subsurf_scatter_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -3035,7 +3496,7 @@ Texture used to control the subsurface scattering strength. Stored in the red te .. rst-class:: classref-property -:ref:`float` **subsurf_scatter_transmittance_boost** = ``0.0`` +:ref:`float` **subsurf_scatter_transmittance_boost** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3052,7 +3513,7 @@ The intensity of the subsurface scattering transmittance effect. .. rst-class:: classref-property -:ref:`Color` **subsurf_scatter_transmittance_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **subsurf_scatter_transmittance_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3069,7 +3530,7 @@ The color to multiply the subsurface scattering transmittance effect with. Ignor .. rst-class:: classref-property -:ref:`float` **subsurf_scatter_transmittance_depth** = ``0.1`` +:ref:`float` **subsurf_scatter_transmittance_depth** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3086,7 +3547,7 @@ The depth of the subsurface scattering transmittance effect. .. rst-class:: classref-property -:ref:`bool` **subsurf_scatter_transmittance_enabled** = ``false`` +:ref:`bool` **subsurf_scatter_transmittance_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3103,7 +3564,7 @@ If ``true``, enables subsurface scattering transmittance. Only effective if :ref .. rst-class:: classref-property -:ref:`Texture2D` **subsurf_scatter_transmittance_texture** +:ref:`Texture2D` **subsurf_scatter_transmittance_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -3120,14 +3581,14 @@ The texture to use for multiplying the intensity of the subsurface scattering tr .. rst-class:: classref-property -:ref:`TextureFilter` **texture_filter** = ``3`` +:ref:`TextureFilter` **texture_filter** = ``3`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_texture_filter**\ (\ value\: :ref:`TextureFilter`\ ) - :ref:`TextureFilter` **get_texture_filter**\ (\ ) -Filter flags for the texture. See :ref:`TextureFilter` for options. +Filter flags for the texture. \ **Note:** :ref:`heightmap_texture` is always sampled with linear filtering, even if nearest-neighbor filtering is selected here. This is to ensure the heightmap effect looks as intended. If you need sharper height transitions between pixels, resize the heightmap texture in an image editor with nearest-neighbor filtering. @@ -3139,14 +3600,14 @@ Filter flags for the texture. See :ref:`TextureFilter` **texture_repeat** = ``true`` +:ref:`bool` **texture_repeat** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) - :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| -Repeat flags for the texture. See :ref:`TextureFilter` for options. +If ``true``, the texture repeats when exceeding the texture's size. See :ref:`FLAG_USE_TEXTURE_REPEAT`. .. rst-class:: classref-item-separator @@ -3156,7 +3617,7 @@ Repeat flags for the texture. See :ref:`TextureFilter` **transparency** = ``0`` +:ref:`Transparency` **transparency** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3169,11 +3630,28 @@ The material's transparency mode. Some transparency modes will disable shadow ca ---- +.. _class_BaseMaterial3D_property_use_fov_override: + +.. rst-class:: classref-property + +:ref:`bool` **use_fov_override** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true`` use :ref:`fov_override` to override the :ref:`Camera3D`'s field of view angle. + +.. rst-class:: classref-item-separator + +---- + .. _class_BaseMaterial3D_property_use_particle_trails: .. rst-class:: classref-property -:ref:`bool` **use_particle_trails** = ``false`` +:ref:`bool` **use_particle_trails** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3190,7 +3668,7 @@ If ``true``, enables parts of the shader required for :ref:`GPUParticles3D` **use_point_size** = ``false`` +:ref:`bool` **use_point_size** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3205,11 +3683,28 @@ If ``true``, render point size can be changed. ---- +.. _class_BaseMaterial3D_property_use_z_clip_scale: + +.. rst-class:: classref-property + +:ref:`bool` **use_z_clip_scale** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +- :ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| + +If ``true`` use :ref:`z_clip_scale` to scale the object being rendered towards the camera to avoid clipping into things like walls. + +.. rst-class:: classref-item-separator + +---- + .. _class_BaseMaterial3D_property_uv1_offset: .. rst-class:: classref-property -:ref:`Vector3` **uv1_offset** = ``Vector3(0, 0, 0)`` +:ref:`Vector3` **uv1_offset** = ``Vector3(0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3226,7 +3721,7 @@ How much to offset the ``UV`` coordinates. This amount will be added to ``UV`` i .. rst-class:: classref-property -:ref:`Vector3` **uv1_scale** = ``Vector3(1, 1, 1)`` +:ref:`Vector3` **uv1_scale** = ``Vector3(1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3243,7 +3738,7 @@ How much to scale the ``UV`` coordinates. This is multiplied by ``UV`` in the ve .. rst-class:: classref-property -:ref:`bool` **uv1_triplanar** = ``false`` +:ref:`bool` **uv1_triplanar** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3260,7 +3755,7 @@ If ``true``, instead of using ``UV`` textures will use a triplanar texture looku .. rst-class:: classref-property -:ref:`float` **uv1_triplanar_sharpness** = ``1.0`` +:ref:`float` **uv1_triplanar_sharpness** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3279,7 +3774,7 @@ A lower number blends the texture more softly while a higher number blends the t .. rst-class:: classref-property -:ref:`bool` **uv1_world_triplanar** = ``false`` +:ref:`bool` **uv1_world_triplanar** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3296,7 +3791,7 @@ If ``true``, triplanar mapping for ``UV`` is calculated in world space rather th .. rst-class:: classref-property -:ref:`Vector3` **uv2_offset** = ``Vector3(0, 0, 0)`` +:ref:`Vector3` **uv2_offset** = ``Vector3(0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3313,7 +3808,7 @@ How much to offset the ``UV2`` coordinates. This amount will be added to ``UV2`` .. rst-class:: classref-property -:ref:`Vector3` **uv2_scale** = ``Vector3(1, 1, 1)`` +:ref:`Vector3` **uv2_scale** = ``Vector3(1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3330,7 +3825,7 @@ How much to scale the ``UV2`` coordinates. This is multiplied by ``UV2`` in the .. rst-class:: classref-property -:ref:`bool` **uv2_triplanar** = ``false`` +:ref:`bool` **uv2_triplanar** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3347,7 +3842,7 @@ If ``true``, instead of using ``UV2`` textures will use a triplanar texture look .. rst-class:: classref-property -:ref:`float` **uv2_triplanar_sharpness** = ``1.0`` +:ref:`float` **uv2_triplanar_sharpness** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3366,7 +3861,7 @@ A lower number blends the texture more softly while a higher number blends the t .. rst-class:: classref-property -:ref:`bool` **uv2_world_triplanar** = ``false`` +:ref:`bool` **uv2_world_triplanar** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3383,7 +3878,7 @@ If ``true``, triplanar mapping for ``UV2`` is calculated in world space rather t .. rst-class:: classref-property -:ref:`bool` **vertex_color_is_srgb** = ``false`` +:ref:`bool` **vertex_color_is_srgb** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3402,7 +3897,7 @@ If ``true``, vertex colors are considered to be stored in sRGB color space and a .. rst-class:: classref-property -:ref:`bool` **vertex_color_use_as_albedo** = ``false`` +:ref:`bool` **vertex_color_use_as_albedo** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -3411,6 +3906,23 @@ If ``true``, vertex colors are considered to be stored in sRGB color space and a If ``true``, the vertex color is used as albedo color. +.. rst-class:: classref-item-separator + +---- + +.. _class_BaseMaterial3D_property_z_clip_scale: + +.. rst-class:: classref-property + +:ref:`float` **z_clip_scale** = ``1.0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_z_clip_scale**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_z_clip_scale**\ (\ ) + +Scales the object being rendered towards the camera to avoid clipping into things like walls. This is intended to be used for objects that are fixed with respect to the camera like player arms, tools, etc. Lighting and shadows will continue to work correctly when this setting is adjusted, but screen-space effects like SSAO and SSR may break with lower scales. Therefore, try to keep this setting as close to ``1.0`` as possible. + .. rst-class:: classref-section-separator ---- @@ -3424,7 +3936,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| +:ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| :ref:`🔗` Returns ``true``, if the specified :ref:`Feature` is enabled. @@ -3436,9 +3948,9 @@ Returns ``true``, if the specified :ref:`Feature` i .. rst-class:: classref-method -:ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| +:ref:`bool` **get_flag**\ (\ flag\: :ref:`Flags`\ ) |const| :ref:`🔗` -Returns ``true``, if the specified flag is enabled. See :ref:`Flags` enumerator for options. +Returns ``true`` if the specified flag is enabled. .. rst-class:: classref-item-separator @@ -3448,7 +3960,7 @@ Returns ``true``, if the specified flag is enabled. See :ref:`Flags` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| +:ref:`Texture2D` **get_texture**\ (\ param\: :ref:`TextureParam`\ ) |const| :ref:`🔗` Returns the :ref:`Texture2D` associated with the specified :ref:`TextureParam`. @@ -3460,7 +3972,7 @@ Returns the :ref:`Texture2D` associated with the specified :ref .. rst-class:: classref-method -|void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) +|void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``true``, enables the specified :ref:`Feature`. Many features that are available in **BaseMaterial3D**\ s need to be enabled before use. This way the cost for using the feature is only incurred when specified. Features can also be enabled by setting the corresponding member to ``true``. @@ -3472,9 +3984,9 @@ If ``true``, enables the specified :ref:`Feature`. .. rst-class:: classref-method -|void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) +|void| **set_flag**\ (\ flag\: :ref:`Flags`, enable\: :ref:`bool`\ ) :ref:`🔗` -If ``true``, enables the specified flag. Flags are optional behavior that can be turned on and off. Only one flag can be enabled at a time with this function, the flag enumerators cannot be bit-masked together to enable or disable multiple flags at once. Flags can also be enabled by setting the corresponding member to ``true``. See :ref:`Flags` enumerator for options. +If ``true``, enables the specified flag. Flags are optional behavior that can be turned on and off. Only one flag can be enabled at a time with this function, the flag enumerators cannot be bit-masked together to enable or disable multiple flags at once. Flags can also be enabled by setting the corresponding member to ``true``. .. rst-class:: classref-item-separator @@ -3484,11 +3996,12 @@ If ``true``, enables the specified flag. Flags are optional behavior that can be .. rst-class:: classref-method -|void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) +|void| **set_texture**\ (\ param\: :ref:`TextureParam`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` -Sets the texture for the slot specified by ``param``. See :ref:`TextureParam` for available slots. +Sets the texture for the slot specified by ``param``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_basis.rst b/classes/class_basis.rst index dbec1dabe26..120a74eba3e 100644 --- a/classes/class_basis.rst +++ b/classes/class_basis.rst @@ -19,13 +19,23 @@ Description The **Basis** built-in :ref:`Variant` type is a 3×3 `matrix `__ used to represent 3D rotation, scale, and shear. It is frequently used within a :ref:`Transform3D`. -A **Basis** is composed by 3 axis vectors, each representing a column of the matrix: :ref:`x`, :ref:`y`, and :ref:`z`. The length of each axis (:ref:`Vector3.length`) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted. +A **Basis** is composed by 3 axis vectors, each representing a column of the matrix: :ref:`x`, :ref:`y`, and :ref:`z`. The length of each axis (:ref:`Vector3.length()`) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted. -A **Basis** is **orthogonal** if its axes are perpendicular to each other. A basis is **normalized** if the length of every axis is ``1``. A basis is **uniform** if all axes share the same length (see :ref:`get_scale`). A basis is **orthonormal** if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is **conformal** if it is both orthogonal and uniform, which ensures it is not distorted. +A **Basis** is: + +- **Orthogonal** if its axes are perpendicular to each other. + +- **Normalized** if the length of every axis is ``1.0``. + +- **Uniform** if all axes share the same length (see :ref:`get_scale()`). + +- **Orthonormal** if it is both orthogonal and normalized, which allows it to only represent rotations (see :ref:`orthonormalized()`). + +- **Conformal** if it is both orthogonal and uniform, which ensures it is not distorted. For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. -\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `Importing 3D Scenes <../tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions>`__ tutorial. +\ **Note:** Godot uses a `right-handed coordinate system `__, which is a common standard. For directions, the convention for built-in types like :ref:`Camera3D` is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the `3D asset direction conventions <../tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions>`__ tutorial. \ **Note:** The basis matrices are exposed as `column-major `__ order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX. @@ -44,13 +54,13 @@ Tutorials - :doc:`Using 3D transforms <../tutorials/3d/using_transforms>` -- `Matrix Transform Demo `__ +- `Matrix Transform Demo `__ -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `3D Voxel Demo `__ +- `3D Voxel Demo `__ -- `2.5D Demo `__ +- `2.5D Game Demo `__ .. rst-class:: classref-reftable-group @@ -125,6 +135,8 @@ Methods +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Basis` | :ref:`scaled`\ (\ scale\: :ref:`Vector3`\ ) |const| | +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Basis` | :ref:`scaled_local`\ (\ scale\: :ref:`Vector3`\ ) |const| | + +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Basis` | :ref:`slerp`\ (\ to\: :ref:`Basis`, weight\: :ref:`float`\ ) |const| | +-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`tdotx`\ (\ with\: :ref:`Vector3`\ ) |const| | @@ -177,9 +189,9 @@ Constants .. rst-class:: classref-constant -**IDENTITY** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`` +**IDENTITY** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`` :ref:`🔗` -The identity basis. This is a basis with no rotation, no shear, and its scale being ``1``. This means that: +The identity **Basis**. This is an orthonormal basis with no rotation, no shear, and a scale of :ref:`Vector3.ONE`. This also means that: - The :ref:`x` points right (:ref:`Vector3.RIGHT`); @@ -189,24 +201,26 @@ The identity basis. This is a basis with no rotation, no shear, and its scale be :: - var basis := Basis.IDENTITY + var basis = Basis.IDENTITY print("| X | Y | Z") - print("| %s | %s | %s" % [basis.x.x, basis.y.x, basis.z.x]) - print("| %s | %s | %s" % [basis.x.y, basis.y.y, basis.z.y]) - print("| %s | %s | %s" % [basis.x.z, basis.y.z, basis.z.z]) + print("| %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x]) + print("| %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y]) + print("| %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z]) # Prints: # | X | Y | Z # | 1 | 0 | 0 # | 0 | 1 | 0 # | 0 | 0 | 1 -This is identical to creating :ref:`Basis` without any parameters. This constant can be used to make your code clearer, and for consistency with C#. +If a :ref:`Vector3` or another **Basis** is transformed (multiplied) by this constant, no transformation occurs. + +\ **Note:** In GDScript, this constant is equivalent to creating a :ref:`Basis` without any arguments. It can be used to make your code clearer, and for consistency with C#. .. _class_Basis_constant_FLIP_X: .. rst-class:: classref-constant -**FLIP_X** = ``Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)`` +**FLIP_X** = ``Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)`` :ref:`🔗` When any basis is multiplied by :ref:`FLIP_X`, it negates all components of the :ref:`x` axis (the X column). @@ -216,7 +230,7 @@ When :ref:`FLIP_X` is multiplied by any basis, it n .. rst-class:: classref-constant -**FLIP_Y** = ``Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)`` +**FLIP_Y** = ``Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)`` :ref:`🔗` When any basis is multiplied by :ref:`FLIP_Y`, it negates all components of the :ref:`y` axis (the Y column). @@ -226,7 +240,7 @@ When :ref:`FLIP_Y` is multiplied by any basis, it n .. rst-class:: classref-constant -**FLIP_Z** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)`` +**FLIP_Z** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)`` :ref:`🔗` When any basis is multiplied by :ref:`FLIP_Z`, it negates all components of the :ref:`z` axis (the Z column). @@ -245,7 +259,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Vector3` **x** = ``Vector3(1, 0, 0)`` +:ref:`Vector3` **x** = ``Vector3(1, 0, 0)`` :ref:`🔗` The basis's X axis, and the column ``0`` of the matrix. @@ -259,7 +273,7 @@ On the identity basis, this vector points right (:ref:`Vector3.RIGHT` **y** = ``Vector3(0, 1, 0)`` +:ref:`Vector3` **y** = ``Vector3(0, 1, 0)`` :ref:`🔗` The basis's Y axis, and the column ``1`` of the matrix. @@ -273,7 +287,7 @@ On the identity basis, this vector points up (:ref:`Vector3.UP` **z** = ``Vector3(0, 0, 1)`` +:ref:`Vector3` **z** = ``Vector3(0, 0, 1)`` :ref:`🔗` The basis's Z axis, and the column ``2`` of the matrix. @@ -292,9 +306,11 @@ Constructor Descriptions .. rst-class:: classref-constructor -:ref:`Basis` **Basis**\ (\ ) +:ref:`Basis` **Basis**\ (\ ) :ref:`🔗` + +Constructs a **Basis** identical to :ref:`IDENTITY`. -Constructs a **Basis** identical to the :ref:`IDENTITY`. +\ **Note:** In C#, this constructs a **Basis** with all of its components set to :ref:`Vector3.ZERO`. .. rst-class:: classref-item-separator @@ -316,7 +332,7 @@ Constructs a **Basis** as a copy of the given **Basis**. Constructs a **Basis** that only represents rotation, rotated around the ``axis`` by the given ``angle``, in radians. The axis must be a normalized vector. -\ **Note:** This is the same as using :ref:`rotated` on the :ref:`IDENTITY` basis. With more than one angle consider using :ref:`from_euler`, instead. +\ **Note:** This is the same as using :ref:`rotated()` on the :ref:`IDENTITY` basis. With more than one angle consider using :ref:`from_euler()`, instead. .. rst-class:: classref-item-separator @@ -353,11 +369,11 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **determinant**\ (\ ) |const| +:ref:`float` **determinant**\ (\ ) |const| :ref:`🔗` Returns the `determinant `__ of this basis's matrix. For advanced math, this number can be used to determine a few attributes: -- If the determinant is exactly ``0``, the basis is not invertible (see :ref:`inverse`). +- If the determinant is exactly ``0.0``, the basis is not invertible (see :ref:`inverse()`). - If the determinant is a negative number, the basis represents a negative scale. @@ -371,13 +387,13 @@ Returns the `determinant `__ of this .. rst-class:: classref-method -:ref:`Basis` **from_euler**\ (\ euler\: :ref:`Vector3`, order\: :ref:`int` = 2\ ) |static| +:ref:`Basis` **from_euler**\ (\ euler\: :ref:`Vector3`, order\: :ref:`int` = 2\ ) |static| :ref:`🔗` Constructs a new **Basis** that only represents rotation from the given :ref:`Vector3` of `Euler angles `__, in radians. -- The :ref:`Vector3.x` should contain the angle around the :ref:`x` axis (pitch). +- The :ref:`Vector3.x` should contain the angle around the :ref:`x` axis (pitch); -- The :ref:`Vector3.y` should contain the angle around the :ref:`y` axis (yaw). +- The :ref:`Vector3.y` should contain the angle around the :ref:`y` axis (yaw); - The :ref:`Vector3.z` should contain the angle around the :ref:`z` axis (roll). @@ -388,19 +404,19 @@ Constructs a new **Basis** that only represents rotation from the given :ref:`Ve # Creates a Basis whose z axis points down. var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0)) - - print(my_basis.z) # Prints (0, -1, 0). + + print(my_basis.z) # Prints (0.0, -1.0, 0.0) .. code-tab:: csharp // Creates a Basis whose z axis points down. var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f)); - - GD.Print(myBasis.Z); // Prints (0, -1, 0). + + GD.Print(myBasis.Z); // Prints (0, -1, 0) -The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): the basis rotates first around the Y axis (yaw), then X (pitch), and lastly Z (roll). When using the opposite method :ref:`get_euler`, this order is reversed. +The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): the basis rotates first around the Y axis (yaw), then X (pitch), and lastly Z (roll). When using the opposite method :ref:`get_euler()`, this order is reversed. .. rst-class:: classref-item-separator @@ -410,7 +426,7 @@ The order of each consecutive rotation can be changed with ``order`` (see :ref:` .. rst-class:: classref-method -:ref:`Basis` **from_scale**\ (\ scale\: :ref:`Vector3`\ ) |static| +:ref:`Basis` **from_scale**\ (\ scale\: :ref:`Vector3`\ ) |static| :ref:`🔗` Constructs a new **Basis** that only represents scale, with no rotation or shear, from the given ``scale`` vector. @@ -420,18 +436,18 @@ Constructs a new **Basis** that only represents scale, with no rotation or shear .. code-tab:: gdscript var my_basis = Basis.from_scale(Vector3(2, 4, 8)) - - print(my_basis.x) # Prints (2, 0, 0). - print(my_basis.y) # Prints (0, 4, 0). - print(my_basis.z) # Prints (0, 0, 8). + + print(my_basis.x) # Prints (2.0, 0.0, 0.0) + print(my_basis.y) # Prints (0.0, 4.0, 0.0) + print(my_basis.z) # Prints (0.0, 0.0, 8.0) .. code-tab:: csharp var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f)); - - GD.Print(myBasis.X); // Prints (2, 0, 0). - GD.Print(myBasis.Y); // Prints (0, 4, 0). - GD.Print(myBasis.Z); // Prints (0, 0, 8). + + GD.Print(myBasis.X); // Prints (2, 0, 0) + GD.Print(myBasis.Y); // Prints (0, 4, 0) + GD.Print(myBasis.Z); // Prints (0, 0, 8) @@ -445,9 +461,9 @@ Constructs a new **Basis** that only represents scale, with no rotation or shear .. rst-class:: classref-method -:ref:`Vector3` **get_euler**\ (\ order\: :ref:`int` = 2\ ) |const| +:ref:`Vector3` **get_euler**\ (\ order\: :ref:`int` = 2\ ) |const| :ref:`🔗` -Returns this basis's rotation as a :ref:`Vector3` of `Euler angles `__, in radians. +Returns this basis's rotation as a :ref:`Vector3` of `Euler angles `__, in radians. For the returned value: - The :ref:`Vector3.x` contains the angle around the :ref:`x` axis (pitch); @@ -455,9 +471,11 @@ Returns this basis's rotation as a :ref:`Vector3` of `Euler angle - The :ref:`Vector3.z` contains the angle around the :ref:`z` axis (roll). -The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method :ref:`from_euler`, this order is reversed. +The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method :ref:`from_euler()`, this order is reversed. -\ **Note:** Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the :ref:`get_rotation_quaternion` method instead, which returns a :ref:`Quaternion`. +\ **Note:** For this method to return correctly, the basis needs to be *orthonormal* (see :ref:`orthonormalized()`). + +\ **Note:** Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the :ref:`get_rotation_quaternion()` method instead, which returns a :ref:`Quaternion`. \ **Note:** In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the :ref:`Node3D.rotation` property. @@ -469,11 +487,11 @@ The order of each consecutive rotation can be changed with ``order`` (see :ref:` .. rst-class:: classref-method -:ref:`Quaternion` **get_rotation_quaternion**\ (\ ) |const| +:ref:`Quaternion` **get_rotation_quaternion**\ (\ ) |const| :ref:`🔗` Returns this basis's rotation as a :ref:`Quaternion`. -\ **Note:** Quatenions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the :ref:`get_euler` method, which returns Euler angles. +\ **Note:** Quaternions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the :ref:`get_euler()` method, which returns Euler angles. .. rst-class:: classref-item-separator @@ -483,9 +501,9 @@ Returns this basis's rotation as a :ref:`Quaternion`. .. rst-class:: classref-method -:ref:`Vector3` **get_scale**\ (\ ) |const| +:ref:`Vector3` **get_scale**\ (\ ) |const| :ref:`🔗` -Returns the length of each axis of this basis, as a :ref:`Vector3`. If the basis is not sheared, this is the scaling factor. It is not affected by rotation. +Returns the length of each axis of this basis, as a :ref:`Vector3`. If the basis is not sheared, this value is the scaling factor. It is not affected by rotation. .. tabs:: @@ -500,8 +518,8 @@ Returns the length of each axis of this basis, as a :ref:`Vector3 # Rotating the Basis in any way preserves its scale. my_basis = my_basis.rotated(Vector3.UP, TAU / 2) my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4) - - print(my_basis.get_scale()) # Prints (2, 4, 8). + + print(my_basis.get_scale()) # Prints (2.0, 4.0, 8.0) .. code-tab:: csharp @@ -513,12 +531,12 @@ Returns the length of each axis of this basis, as a :ref:`Vector3 // Rotating the Basis in any way preserves its scale. myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f); myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f); - - GD.Print(myBasis.Scale); // Prints (2, 4, 8). + + GD.Print(myBasis.Scale); // Prints (2, 4, 8) -\ **Note:** If the value returned by :ref:`determinant` is negative, the scale is also negative. +\ **Note:** If the value returned by :ref:`determinant()` is negative, the scale is also negative. .. rst-class:: classref-item-separator @@ -528,7 +546,7 @@ Returns the length of each axis of this basis, as a :ref:`Vector3 .. rst-class:: classref-method -:ref:`Basis` **inverse**\ (\ ) |const| +:ref:`Basis` **inverse**\ (\ ) |const| :ref:`🔗` Returns the `inverse of this basis's matrix `__. @@ -540,7 +558,7 @@ Returns the `inverse of this basis's matrix ` **is_conformal**\ (\ ) |const| +:ref:`bool` **is_conformal**\ (\ ) |const| :ref:`🔗` Returns ``true`` if this basis is conformal. A conformal basis is both *orthogonal* (the axes are perpendicular to each other) and *uniform* (the axes share the same length). This method can be especially useful during physics calculations. @@ -552,9 +570,9 @@ Returns ``true`` if this basis is conformal. A conformal basis is both *orthogon .. rst-class:: classref-method -:ref:`bool` **is_equal_approx**\ (\ b\: :ref:`Basis`\ ) |const| +:ref:`bool` **is_equal_approx**\ (\ b\: :ref:`Basis`\ ) |const| :ref:`🔗` -Returns ``true`` if this basis and ``b`` are approximately equal, by calling :ref:`@GlobalScope.is_equal_approx` on all vector components. +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 @@ -564,9 +582,9 @@ Returns ``true`` if this basis and ``b`` are approximately equal, by calling :re .. rst-class:: classref-method -:ref:`bool` **is_finite**\ (\ ) |const| +:ref:`bool` **is_finite**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite` on all vector components. +Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finite()` on all vector components. .. rst-class:: classref-item-separator @@ -576,13 +594,15 @@ Returns ``true`` if this basis is finite, by calling :ref:`@GlobalScope.is_finit .. rst-class:: classref-method -:ref:`Basis` **looking_at**\ (\ target\: :ref:`Vector3`, up\: :ref:`Vector3` = Vector3(0, 1, 0), use_model_front\: :ref:`bool` = false\ ) |static| +:ref:`Basis` **looking_at**\ (\ target\: :ref:`Vector3`, up\: :ref:`Vector3` = Vector3(0, 1, 0), use_model_front\: :ref:`bool` = false\ ) |static| :ref:`🔗` Creates a new **Basis** with a rotation such that the forward axis (-Z) points towards the ``target`` position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right). If ``use_model_front`` is ``true``, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the ``target`` position. -The up axis (+Y) points as close to the ``up`` vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see :ref:`orthonormalized`). The ``target`` and ``up`` vectors cannot be :ref:`Vector3.ZERO`, and cannot be parallel to each other. +The up axis (+Y) points as close to the ``up`` vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see :ref:`orthonormalized()`). + +The ``target`` and the ``up`` cannot be :ref:`Vector3.ZERO`, and shouldn't be colinear to avoid unintended rotation around local Z axis. .. rst-class:: classref-item-separator @@ -592,9 +612,9 @@ The up axis (+Y) points as close to the ``up`` vector as possible while staying .. rst-class:: classref-method -:ref:`Basis` **orthonormalized**\ (\ ) |const| +:ref:`Basis` **orthonormalized**\ (\ ) |const| :ref:`🔗` -Returns the orthonormalized version of this basis. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1``), which also means it can only represent rotation. +Returns the orthonormalized version of this basis. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1.0``), which also means it can only represent a rotation. It is often useful to call this method to avoid rounding errors on a rotating basis: @@ -607,7 +627,6 @@ It is often useful to call this method to avoid rounding errors on a rotating ba func _process(delta): basis = basis.rotated(Vector3.UP, TAU * delta) basis = basis.rotated(Vector3.RIGHT, TAU * delta) - basis = basis.orthonormalized() .. code-tab:: csharp @@ -616,8 +635,8 @@ It is often useful to call this method to avoid rounding errors on a rotating ba public override void _Process(double delta) { Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta) - .Rotated(Vector3.Right, Mathf.Tau * (float)delta) - .Orthonormalized(); + .Rotated(Vector3.Right, Mathf.Tau * (float)delta) + .Orthonormalized(); } @@ -630,11 +649,11 @@ It is often useful to call this method to avoid rounding errors on a rotating ba .. rst-class:: classref-method -:ref:`Basis` **rotated**\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) |const| +:ref:`Basis` **rotated**\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) |const| :ref:`🔗` -Returns this basis rotated around the given ``axis`` by ``angle`` (in radians). The ``axis`` must be a normalized vector (see :ref:`Vector3.normalized`). +Returns a copy of this basis rotated around the given ``axis`` by the given ``angle`` (in radians). -Positive values rotate this basis clockwise around the axis, while negative values rotate it counterclockwise. +The ``axis`` must be a normalized vector (see :ref:`Vector3.normalized()`). If ``angle`` is positive, the basis is rotated counter-clockwise around the axis. .. tabs:: @@ -643,7 +662,7 @@ Positive values rotate this basis clockwise around the axis, while negative valu var my_basis = Basis.IDENTITY var angle = TAU / 2 - + my_basis = my_basis.rotated(Vector3.UP, angle) # Rotate around the up axis (yaw). my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch). my_basis = my_basis.rotated(Vector3.BACK, angle) # Rotate around the back axis (roll). @@ -652,7 +671,7 @@ Positive values rotate this basis clockwise around the axis, while negative valu var myBasis = Basis.Identity; var angle = Mathf.Tau / 2.0f; - + myBasis = myBasis.Rotated(Vector3.Up, angle); // Rotate around the up axis (yaw). myBasis = myBasis.Rotated(Vector3.Right, angle); // Rotate around the right axis (pitch). myBasis = myBasis.Rotated(Vector3.Back, angle); // Rotate around the back axis (roll). @@ -667,7 +686,7 @@ Positive values rotate this basis clockwise around the axis, while negative valu .. rst-class:: classref-method -:ref:`Basis` **scaled**\ (\ scale\: :ref:`Vector3`\ ) |const| +:ref:`Basis` **scaled**\ (\ scale\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns this basis with each axis's components scaled by the given ``scale``'s components. @@ -684,10 +703,10 @@ The basis matrix's rows are multiplied by ``scale``'s components. This operation Vector3(3, 3, 3) ) my_basis = my_basis.scaled(Vector3(0, 2, -2)) - - print(my_basis.x) # Prints (0, 2, -2). - print(my_basis.y) # Prints (0, 4, -4). - print(my_basis.z) # Prints (0, 6, -6). + + print(my_basis.x) # Prints (0.0, 2.0, -2.0) + print(my_basis.y) # Prints (0.0, 4.0, -4.0) + print(my_basis.z) # Prints (0.0, 6.0, -6.0) .. code-tab:: csharp @@ -697,10 +716,55 @@ The basis matrix's rows are multiplied by ``scale``'s components. This operation new Vector3(3.0f, 3.0f, 3.0f) ); myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f)); - - GD.Print(myBasis.X); // Prints (0, 2, -2). - GD.Print(myBasis.Y); // Prints (0, 4, -4). - GD.Print(myBasis.Z); // Prints (0, 6, -6). + + GD.Print(myBasis.X); // Prints (0, 2, -2) + GD.Print(myBasis.Y); // Prints (0, 4, -4) + GD.Print(myBasis.Z); // Prints (0, 6, -6) + + + +.. rst-class:: classref-item-separator + +---- + +.. _class_Basis_method_scaled_local: + +.. rst-class:: classref-method + +:ref:`Basis` **scaled_local**\ (\ scale\: :ref:`Vector3`\ ) |const| :ref:`🔗` + +Returns this basis with each axis scaled by the corresponding component in the given ``scale``. + +The basis matrix's columns are multiplied by ``scale``'s components. This operation is a local scale (relative to self). + + +.. tabs:: + + .. code-tab:: gdscript + + var my_basis = Basis( + Vector3(1, 1, 1), + Vector3(2, 2, 2), + Vector3(3, 3, 3) + ) + my_basis = my_basis.scaled_local(Vector3(0, 2, -2)) + + print(my_basis.x) # Prints (0.0, 0.0, 0.0) + print(my_basis.y) # Prints (4.0, 4.0, 4.0) + print(my_basis.z) # Prints (-6.0, -6.0, -6.0) + + .. code-tab:: csharp + + var myBasis = new Basis( + new Vector3(1.0f, 1.0f, 1.0f), + new Vector3(2.0f, 2.0f, 2.0f), + new Vector3(3.0f, 3.0f, 3.0f) + ); + myBasis = myBasis.ScaledLocal(new Vector3(0.0f, 2.0f, -2.0f)); + + GD.Print(myBasis.X); // Prints (0, 0, 0) + GD.Print(myBasis.Y); // Prints (4, 4, 4) + GD.Print(myBasis.Z); // Prints (-6, -6, -6) @@ -712,20 +776,20 @@ The basis matrix's rows are multiplied by ``scale``'s components. This operation .. rst-class:: classref-method -:ref:`Basis` **slerp**\ (\ to\: :ref:`Basis`, weight\: :ref:`float`\ ) |const| +:ref:`Basis` **slerp**\ (\ to\: :ref:`Basis`, weight\: :ref:`float`\ ) |const| :ref:`🔗` Performs a spherical-linear interpolation with the ``to`` basis, given a ``weight``. Both this basis and ``to`` should represent a rotation. -\ **Example:** Smoothly rotate a :ref:`Node3D` to the target basis over time, with a :ref:`Tween`. +\ **Example:** Smoothly rotate a :ref:`Node3D` to the target basis over time, with a :ref:`Tween`: :: var start_basis = Basis.IDENTITY var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2) - + func _ready(): create_tween().tween_method(interpolate, 0.0, 1.0, 5.0).set_trans(Tween.TRANS_EXPO) - + func interpolate(weight): basis = start_basis.slerp(target_basis, weight) @@ -737,9 +801,9 @@ Performs a spherical-linear interpolation with the ``to`` basis, given a ``weigh .. rst-class:: classref-method -:ref:`float` **tdotx**\ (\ with\: :ref:`Vector3`\ ) |const| +:ref:`float` **tdotx**\ (\ with\: :ref:`Vector3`\ ) |const| :ref:`🔗` -Returns the transposed dot product between ``with`` and the :ref:`x` axis (see :ref:`transposed`). +Returns the transposed dot product between ``with`` and the :ref:`x` axis (see :ref:`transposed()`). This is equivalent to ``basis.x.dot(vector)``. @@ -751,9 +815,9 @@ This is equivalent to ``basis.x.dot(vector)``. .. rst-class:: classref-method -:ref:`float` **tdoty**\ (\ with\: :ref:`Vector3`\ ) |const| +:ref:`float` **tdoty**\ (\ with\: :ref:`Vector3`\ ) |const| :ref:`🔗` -Returns the transposed dot product between ``with`` and the :ref:`y` axis (see :ref:`transposed`). +Returns the transposed dot product between ``with`` and the :ref:`y` axis (see :ref:`transposed()`). This is equivalent to ``basis.y.dot(vector)``. @@ -765,9 +829,9 @@ This is equivalent to ``basis.y.dot(vector)``. .. rst-class:: classref-method -:ref:`float` **tdotz**\ (\ with\: :ref:`Vector3`\ ) |const| +:ref:`float` **tdotz**\ (\ with\: :ref:`Vector3`\ ) |const| :ref:`🔗` -Returns the transposed dot product between ``with`` and the :ref:`z` axis (see :ref:`transposed`). +Returns the transposed dot product between ``with`` and the :ref:`z` axis (see :ref:`transposed()`). This is equivalent to ``basis.z.dot(vector)``. @@ -779,7 +843,7 @@ This is equivalent to ``basis.z.dot(vector)``. .. rst-class:: classref-method -:ref:`Basis` **transposed**\ (\ ) |const| +:ref:`Basis` **transposed**\ (\ ) |const| :ref:`🔗` Returns the transposed version of this basis. This turns the basis matrix's columns into rows, and its rows into columns. @@ -794,10 +858,10 @@ Returns the transposed version of this basis. This turns the basis matrix's colu Vector3(7, 8, 9) ) my_basis = my_basis.transposed() - - print(my_basis.x) # Prints (1, 4, 7). - print(my_basis.y) # Prints (2, 5, 8). - print(my_basis.z) # Prints (3, 6, 9). + + print(my_basis.x) # Prints (1.0, 4.0, 7.0) + print(my_basis.y) # Prints (2.0, 5.0, 8.0) + print(my_basis.z) # Prints (3.0, 6.0, 9.0) .. code-tab:: csharp @@ -807,10 +871,10 @@ Returns the transposed version of this basis. This turns the basis matrix's colu new Vector3(7.0f, 8.0f, 9.0f) ); myBasis = myBasis.Transposed(); - - GD.Print(myBasis.X); // Prints (1, 4, 7). - GD.Print(myBasis.Y); // Prints (2, 5, 8). - GD.Print(myBasis.Z); // Prints (3, 6, 9). + + GD.Print(myBasis.X); // Prints (1, 4, 7) + GD.Print(myBasis.Y); // Prints (2, 5, 8) + GD.Print(myBasis.Z); // Prints (3, 6, 9) @@ -827,11 +891,11 @@ Operator Descriptions .. rst-class:: classref-operator -:ref:`bool` **operator !=**\ (\ right\: :ref:`Basis`\ ) +:ref:`bool` **operator !=**\ (\ right\: :ref:`Basis`\ ) :ref:`🔗` Returns ``true`` if the components of both **Basis** matrices are not equal. -\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. .. rst-class:: classref-item-separator @@ -841,7 +905,7 @@ Returns ``true`` if the components of both **Basis** matrices are not equal. .. rst-class:: classref-operator -:ref:`Basis` **operator ***\ (\ right\: :ref:`Basis`\ ) +:ref:`Basis` **operator ***\ (\ right\: :ref:`Basis`\ ) :ref:`🔗` Transforms (multiplies) the ``right`` basis by this basis. @@ -855,7 +919,7 @@ This is the operation performed between parent and child :ref:`Node3D` **operator ***\ (\ right\: :ref:`Vector3`\ ) +:ref:`Vector3` **operator ***\ (\ right\: :ref:`Vector3`\ ) :ref:`🔗` Transforms (multiplies) the ``right`` vector by this basis, returning a :ref:`Vector3`. @@ -864,13 +928,15 @@ Transforms (multiplies) the ``right`` vector by this basis, returning a :ref:`Ve .. code-tab:: gdscript - var my_basis = Basis(Vector3(1, 1, 1), Vector3(1, 1, 1), Vector3(0, 2, 5)) - print(my_basis * Vector3(1, 2, 3)) # Prints (7, 3, 16) + # Basis that swaps the X/Z axes and doubles the scale. + var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2)) + print(my_basis * Vector3(1, 2, 3)) # Prints (4.0, 2.0, 6.0) .. code-tab:: csharp - var myBasis = new Basis(new Vector3(1, 1, 1), new Vector3(1, 1, 1), new Vector3(0, 2, 5)); - GD.Print(my_basis * new Vector3(1, 2, 3)); // Prints (7, 3, 16) + // Basis that swaps the X/Z axes and doubles the scale. + var myBasis = new Basis(new Vector3(0, 2, 0), new Vector3(2, 0, 0), new Vector3(0, 0, 2)); + GD.Print(myBasis * new Vector3(1, 2, 3)); // Prints (4, 2, 6) @@ -882,7 +948,7 @@ Transforms (multiplies) the ``right`` vector by this basis, returning a :ref:`Ve .. rst-class:: classref-operator -:ref:`Basis` **operator ***\ (\ right\: :ref:`float`\ ) +:ref:`Basis` **operator ***\ (\ right\: :ref:`float`\ ) :ref:`🔗` Multiplies all components of the **Basis** by the given :ref:`float`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. @@ -894,7 +960,7 @@ Multiplies all components of the **Basis** by the given :ref:`float .. rst-class:: classref-operator -:ref:`Basis` **operator ***\ (\ right\: :ref:`int`\ ) +:ref:`Basis` **operator ***\ (\ right\: :ref:`int`\ ) :ref:`🔗` Multiplies all components of the **Basis** by the given :ref:`int`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. @@ -906,7 +972,7 @@ Multiplies all components of the **Basis** by the given :ref:`int`. T .. rst-class:: classref-operator -:ref:`Basis` **operator /**\ (\ right\: :ref:`float`\ ) +:ref:`Basis` **operator /**\ (\ right\: :ref:`float`\ ) :ref:`🔗` Divides all components of the **Basis** by the given :ref:`float`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. @@ -918,7 +984,7 @@ Divides all components of the **Basis** by the given :ref:`float`. .. rst-class:: classref-operator -:ref:`Basis` **operator /**\ (\ right\: :ref:`int`\ ) +:ref:`Basis` **operator /**\ (\ right\: :ref:`int`\ ) :ref:`🔗` Divides all components of the **Basis** by the given :ref:`int`. This affects the basis's scale uniformly, resizing all 3 axes by the ``right`` value. @@ -930,11 +996,11 @@ Divides all components of the **Basis** by the given :ref:`int`. This .. rst-class:: classref-operator -:ref:`bool` **operator ==**\ (\ right\: :ref:`Basis`\ ) +:ref:`bool` **operator ==**\ (\ right\: :ref:`Basis`\ ) :ref:`🔗` Returns ``true`` if the components of both **Basis** matrices are exactly equal. -\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. .. rst-class:: classref-item-separator @@ -944,13 +1010,14 @@ Returns ``true`` if the components of both **Basis** matrices are exactly equal. .. rst-class:: classref-operator -:ref:`Vector3` **operator []**\ (\ index\: :ref:`int`\ ) +:ref:`Vector3` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Accesses each axis (column) of this basis by their index. Index ``0`` is the same as :ref:`x`, index ``1`` is the same as :ref:`y`, and index ``2`` is the same as :ref:`z`. \ **Note:** In C++, this operator accesses the rows of the basis matrix, *not* the columns. For the same behavior as scripting languages, use the ``set_column`` and ``get_column`` methods. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_bitmap.rst b/classes/class_bitmap.rst index 3921c5ae443..c03a2f92e7a 100644 --- a/classes/class_bitmap.rst +++ b/classes/class_bitmap.rst @@ -70,9 +70,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Image` **convert_to_image**\ (\ ) |const| +:ref:`Image` **convert_to_image**\ (\ ) |const| :ref:`🔗` -Returns an image of the same size as the bitmap and with a :ref:`Format` of type :ref:`Image.FORMAT_L8`. ``true`` bits of the bitmap are being converted into white pixels, and ``false`` bits into black. +Returns an image of the same size as the bitmap and with an :ref:`Format` of type :ref:`Image.FORMAT_L8`. ``true`` bits of the bitmap are being converted into white pixels, and ``false`` bits into black. .. rst-class:: classref-item-separator @@ -82,7 +82,7 @@ Returns an image of the same size as the bitmap and with a :ref:`Format`\ ) +|void| **create**\ (\ size\: :ref:`Vector2i`\ ) :ref:`🔗` Creates a bitmap with the specified size, filled with ``false``. @@ -94,7 +94,7 @@ Creates a bitmap with the specified size, filled with ``false``. .. rst-class:: classref-method -|void| **create_from_image_alpha**\ (\ image\: :ref:`Image`, threshold\: :ref:`float` = 0.1\ ) +|void| **create_from_image_alpha**\ (\ image\: :ref:`Image`, threshold\: :ref:`float` = 0.1\ ) :ref:`🔗` Creates a bitmap that matches the given image dimensions, every element of the bitmap is set to ``false`` if the alpha value of the image at that position is equal to ``threshold`` or less, and ``true`` in other case. @@ -106,7 +106,7 @@ Creates a bitmap that matches the given image dimensions, every element of the b .. rst-class:: classref-method -:ref:`bool` **get_bit**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| +:ref:`bool` **get_bit**\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| :ref:`🔗` Returns bitmap's value at the specified position. @@ -118,7 +118,7 @@ Returns bitmap's value at the specified position. .. rst-class:: classref-method -:ref:`bool` **get_bitv**\ (\ position\: :ref:`Vector2i`\ ) |const| +:ref:`bool` **get_bitv**\ (\ position\: :ref:`Vector2i`\ ) |const| :ref:`🔗` Returns bitmap's value at the specified position. @@ -130,7 +130,7 @@ Returns bitmap's value at the specified position. .. rst-class:: classref-method -:ref:`Vector2i` **get_size**\ (\ ) |const| +:ref:`Vector2i` **get_size**\ (\ ) |const| :ref:`🔗` Returns bitmap's dimensions. @@ -142,7 +142,7 @@ Returns bitmap's dimensions. .. rst-class:: classref-method -:ref:`int` **get_true_bit_count**\ (\ ) |const| +:ref:`int` **get_true_bit_count**\ (\ ) |const| :ref:`🔗` Returns the number of bitmap elements that are set to ``true``. @@ -154,9 +154,9 @@ Returns the number of bitmap elements that are set to ``true``. .. rst-class:: classref-method -|void| **grow_mask**\ (\ pixels\: :ref:`int`, rect\: :ref:`Rect2i`\ ) +|void| **grow_mask**\ (\ pixels\: :ref:`int`, rect\: :ref:`Rect2i`\ ) :ref:`🔗` -Applies morphological dilation or erosion to the bitmap. If ``pixels`` is positive, dilation is applied to the bitmap. If ``pixels`` is negative, erosion is applied to the bitmap. ``rect`` defines the area where the morphological operation is applied. Pixels located outside the ``rect`` are unaffected by :ref:`grow_mask`. +Applies morphological dilation or erosion to the bitmap. If ``pixels`` is positive, dilation is applied to the bitmap. If ``pixels`` is negative, erosion is applied to the bitmap. ``rect`` defines the area where the morphological operation is applied. Pixels located outside the ``rect`` are unaffected by :ref:`grow_mask()`. .. rst-class:: classref-item-separator @@ -166,7 +166,7 @@ Applies morphological dilation or erosion to the bitmap. If ``pixels`` is positi .. rst-class:: classref-method -:ref:`Array`\[:ref:`PackedVector2Array`\] **opaque_to_polygons**\ (\ rect\: :ref:`Rect2i`, epsilon\: :ref:`float` = 2.0\ ) |const| +:ref:`Array`\[:ref:`PackedVector2Array`\] **opaque_to_polygons**\ (\ rect\: :ref:`Rect2i`, epsilon\: :ref:`float` = 2.0\ ) |const| :ref:`🔗` Creates an :ref:`Array` of polygons covering a rectangular portion of the bitmap. It uses a marching squares algorithm, followed by Ramer-Douglas-Peucker (RDP) reduction of the number of vertices. Each polygon is described as a :ref:`PackedVector2Array` of its vertices. @@ -186,7 +186,7 @@ To get polygons covering the whole bitmap, pass: .. rst-class:: classref-method -|void| **resize**\ (\ new_size\: :ref:`Vector2i`\ ) +|void| **resize**\ (\ new_size\: :ref:`Vector2i`\ ) :ref:`🔗` Resizes the image to ``new_size``. @@ -198,7 +198,7 @@ Resizes the image to ``new_size``. .. rst-class:: classref-method -|void| **set_bit**\ (\ x\: :ref:`int`, y\: :ref:`int`, bit\: :ref:`bool`\ ) +|void| **set_bit**\ (\ x\: :ref:`int`, y\: :ref:`int`, bit\: :ref:`bool`\ ) :ref:`🔗` Sets the bitmap's element at the specified position, to the specified value. @@ -210,7 +210,7 @@ Sets the bitmap's element at the specified position, to the specified value. .. rst-class:: classref-method -|void| **set_bit_rect**\ (\ rect\: :ref:`Rect2i`, bit\: :ref:`bool`\ ) +|void| **set_bit_rect**\ (\ rect\: :ref:`Rect2i`, bit\: :ref:`bool`\ ) :ref:`🔗` Sets a rectangular portion of the bitmap to the specified value. @@ -222,11 +222,12 @@ Sets a rectangular portion of the bitmap to the specified value. .. rst-class:: classref-method -|void| **set_bitv**\ (\ position\: :ref:`Vector2i`, bit\: :ref:`bool`\ ) +|void| **set_bitv**\ (\ position\: :ref:`Vector2i`, bit\: :ref:`bool`\ ) :ref:`🔗` Sets the bitmap's element at the specified position, to the specified value. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_bone2d.rst b/classes/class_bone2d.rst index cdd73514b34..3bb0ff901d8 100644 --- a/classes/class_bone2d.rst +++ b/classes/class_bone2d.rst @@ -23,7 +23,7 @@ A hierarchy of **Bone2D**\ s can be bound to a :ref:`Skeleton2D` nodes to animate 2D meshes created with the :ref:`Polygon2D` UV editor. -Each bone has a :ref:`rest` transform that you can reset to with :ref:`apply_rest`. These rest poses are relative to the bone's parent. +Each bone has a :ref:`rest` transform that you can reset to with :ref:`apply_rest()`. These rest poses are relative to the bone's parent. If in the editor, you can set the rest pose of an entire skeleton using a menu option, from the code, you need to iterate over the bones to set their individual rest poses. @@ -80,14 +80,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Transform2D` **rest** = ``Transform2D(0, 0, 0, 0, 0, 0)`` +:ref:`Transform2D` **rest** = ``Transform2D(0, 0, 0, 0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_rest**\ (\ value\: :ref:`Transform2D`\ ) - :ref:`Transform2D` **get_rest**\ (\ ) -Rest transform of the bone. You can reset the node's transforms to this value using :ref:`apply_rest`. +Rest transform of the bone. You can reset the node's transforms to this value using :ref:`apply_rest()`. .. rst-class:: classref-section-separator @@ -102,7 +102,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **apply_rest**\ (\ ) +|void| **apply_rest**\ (\ ) :ref:`🔗` Resets the bone to the rest pose. This is equivalent to setting :ref:`Node2D.transform` to :ref:`rest`. @@ -114,7 +114,7 @@ Resets the bone to the rest pose. This is equivalent to setting :ref:`Node2D.tra .. rst-class:: classref-method -:ref:`bool` **get_autocalculate_length_and_angle**\ (\ ) |const| +:ref:`bool` **get_autocalculate_length_and_angle**\ (\ ) |const| :ref:`🔗` Returns whether this **Bone2D** is going to autocalculate its length and bone angle using its first **Bone2D** child node, if one exists. If there are no **Bone2D** children, then it cannot autocalculate these values and will print a warning. @@ -126,7 +126,7 @@ Returns whether this **Bone2D** is going to autocalculate its length and bone an .. rst-class:: classref-method -:ref:`float` **get_bone_angle**\ (\ ) |const| +:ref:`float` **get_bone_angle**\ (\ ) |const| :ref:`🔗` Returns the angle of the bone in the **Bone2D**. @@ -140,7 +140,7 @@ Returns the angle of the bone in the **Bone2D**. .. rst-class:: classref-method -:ref:`int` **get_index_in_skeleton**\ (\ ) |const| +:ref:`int` **get_index_in_skeleton**\ (\ ) |const| :ref:`🔗` Returns the node's index as part of the entire skeleton. See :ref:`Skeleton2D`. @@ -152,7 +152,7 @@ Returns the node's index as part of the entire skeleton. See :ref:`Skeleton2D` **get_length**\ (\ ) |const| +:ref:`float` **get_length**\ (\ ) |const| :ref:`🔗` Returns the length of the bone in the **Bone2D** node. @@ -164,7 +164,7 @@ Returns the length of the bone in the **Bone2D** node. .. rst-class:: classref-method -:ref:`Transform2D` **get_skeleton_rest**\ (\ ) |const| +:ref:`Transform2D` **get_skeleton_rest**\ (\ ) |const| :ref:`🔗` Returns the node's :ref:`rest` :ref:`Transform2D` if it doesn't have a parent, or its rest pose relative to its parent. @@ -176,7 +176,7 @@ Returns the node's :ref:`rest` :ref:`Transform2D`\ ) +|void| **set_autocalculate_length_and_angle**\ (\ auto_calculate\: :ref:`bool`\ ) :ref:`🔗` When set to ``true``, the **Bone2D** node will attempt to automatically calculate the bone angle and length using the first child **Bone2D** node, if one exists. If none exist, the **Bone2D** cannot automatically calculate these values and will print a warning. @@ -188,7 +188,7 @@ When set to ``true``, the **Bone2D** node will attempt to automatically calculat .. rst-class:: classref-method -|void| **set_bone_angle**\ (\ angle\: :ref:`float`\ ) +|void| **set_bone_angle**\ (\ angle\: :ref:`float`\ ) :ref:`🔗` Sets the bone angle for the **Bone2D**. This is typically set to the rotation from the **Bone2D** to a child **Bone2D** node. @@ -202,11 +202,12 @@ Sets the bone angle for the **Bone2D**. This is typically set to the rotation fr .. rst-class:: classref-method -|void| **set_length**\ (\ length\: :ref:`float`\ ) +|void| **set_length**\ (\ length\: :ref:`float`\ ) :ref:`🔗` Sets the length of the bone in the **Bone2D**. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_boneattachment3d.rst b/classes/class_boneattachment3d.rst index 727d5ac0694..6a85f3bf96a 100644 --- a/classes/class_boneattachment3d.rst +++ b/classes/class_boneattachment3d.rst @@ -32,13 +32,19 @@ Properties .. table:: :widths: auto - +-----------------------------+---------------------------------------------------------------------+-----------+ - | :ref:`int` | :ref:`bone_idx` | ``-1`` | - +-----------------------------+---------------------------------------------------------------------+-----------+ - | :ref:`String` | :ref:`bone_name` | ``""`` | - +-----------------------------+---------------------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`override_pose` | ``false`` | - +-----------------------------+---------------------------------------------------------------------+-----------+ + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`bone_idx` | ``-1`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`bone_name` | ``""`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`external_skeleton` | | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`override_pose` | ``false`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`PhysicsInterpolationMode` | physics_interpolation_mode | ``2`` (overrides :ref:`Node`) | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`use_external_skeleton` | ``false`` | + +---------------------------------------------------------------------+-------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -48,17 +54,11 @@ Methods .. table:: :widths: auto - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`NodePath` | :ref:`get_external_skeleton`\ (\ ) |const| | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_use_external_skeleton`\ (\ ) |const| | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`on_bone_pose_update`\ (\ bone_index\: :ref:`int`\ ) | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_external_skeleton`\ (\ external_skeleton\: :ref:`NodePath`\ ) | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_use_external_skeleton`\ (\ use_external_skeleton\: :ref:`bool`\ ) | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------+-----------------------------------------------------------------------------------+ + | :ref:`Skeleton3D` | :ref:`get_skeleton`\ (\ ) | + +-------------------------------------+-----------------------------------------------------------------------------------+ + | |void| | :ref:`on_skeleton_update`\ (\ ) | + +-------------------------------------+-----------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -73,7 +73,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **bone_idx** = ``-1`` +:ref:`int` **bone_idx** = ``-1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -90,7 +90,7 @@ The index of the attached bone. .. rst-class:: classref-property -:ref:`String` **bone_name** = ``""`` +:ref:`String` **bone_name** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -103,85 +103,86 @@ The name of the attached bone. ---- -.. _class_BoneAttachment3D_property_override_pose: +.. _class_BoneAttachment3D_property_external_skeleton: .. rst-class:: classref-property -:ref:`bool` **override_pose** = ``false`` +:ref:`NodePath` **external_skeleton** :ref:`🔗` .. rst-class:: classref-property-setget -- |void| **set_override_pose**\ (\ value\: :ref:`bool`\ ) -- :ref:`bool` **get_override_pose**\ (\ ) +- |void| **set_external_skeleton**\ (\ value\: :ref:`NodePath`\ ) +- :ref:`NodePath` **get_external_skeleton**\ (\ ) -Whether the BoneAttachment3D node will override the bone pose of the bone it is attached to. When set to ``true``, the BoneAttachment3D node can change the pose of the bone. When set to ``false``, the BoneAttachment3D will always be set to the bone's transform. +The :ref:`NodePath` to the external :ref:`Skeleton3D` node. -.. rst-class:: classref-section-separator +.. rst-class:: classref-item-separator ---- -.. rst-class:: classref-descriptions-group +.. _class_BoneAttachment3D_property_override_pose: -Method Descriptions -------------------- +.. rst-class:: classref-property -.. _class_BoneAttachment3D_method_get_external_skeleton: +:ref:`bool` **override_pose** = ``false`` :ref:`🔗` -.. rst-class:: classref-method +.. rst-class:: classref-property-setget + +- |void| **set_override_pose**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_override_pose**\ (\ ) -:ref:`NodePath` **get_external_skeleton**\ (\ ) |const| +Whether the **BoneAttachment3D** node will override the bone pose of the bone it is attached to. When set to ``true``, the **BoneAttachment3D** node can change the pose of the bone. When set to ``false``, the **BoneAttachment3D** will always be set to the bone's transform. -Returns the :ref:`NodePath` to the external :ref:`Skeleton3D` node, if one has been set. +\ **Note:** This override performs interruptively in the skeleton update process using signals due to the old design. It may cause unintended behavior when used at the same time with :ref:`SkeletonModifier3D`. .. rst-class:: classref-item-separator ---- -.. _class_BoneAttachment3D_method_get_use_external_skeleton: +.. _class_BoneAttachment3D_property_use_external_skeleton: -.. rst-class:: classref-method - -:ref:`bool` **get_use_external_skeleton**\ (\ ) |const| - -Returns whether the BoneAttachment3D node is using an external :ref:`Skeleton3D` rather than attempting to use its parent node as the :ref:`Skeleton3D`. +.. rst-class:: classref-property -.. rst-class:: classref-item-separator +:ref:`bool` **use_external_skeleton** = ``false`` :ref:`🔗` ----- +.. rst-class:: classref-property-setget -.. _class_BoneAttachment3D_method_on_bone_pose_update: +- |void| **set_use_external_skeleton**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_use_external_skeleton**\ (\ ) -.. rst-class:: classref-method +Whether the **BoneAttachment3D** node will use an external :ref:`Skeleton3D` node rather than attempting to use its parent node as the :ref:`Skeleton3D`. When set to ``true``, the **BoneAttachment3D** node will use the external :ref:`Skeleton3D` node set in :ref:`external_skeleton`. -|void| **on_bone_pose_update**\ (\ bone_index\: :ref:`int`\ ) +.. rst-class:: classref-section-separator -A function that is called automatically when the :ref:`Skeleton3D` the BoneAttachment3D node is using has a bone that has changed its pose. This function is where the BoneAttachment3D node updates its position so it is correctly bound when it is *not* set to override the bone pose. +---- -.. rst-class:: classref-item-separator +.. rst-class:: classref-descriptions-group ----- +Method Descriptions +------------------- -.. _class_BoneAttachment3D_method_set_external_skeleton: +.. _class_BoneAttachment3D_method_get_skeleton: .. rst-class:: classref-method -|void| **set_external_skeleton**\ (\ external_skeleton\: :ref:`NodePath`\ ) +:ref:`Skeleton3D` **get_skeleton**\ (\ ) :ref:`🔗` -Sets the :ref:`NodePath` to the external skeleton that the BoneAttachment3D node should use. See :ref:`set_use_external_skeleton` to enable the external :ref:`Skeleton3D` node. +Returns the parent or external :ref:`Skeleton3D` node if it exists, otherwise returns ``null``. .. rst-class:: classref-item-separator ---- -.. _class_BoneAttachment3D_method_set_use_external_skeleton: +.. _class_BoneAttachment3D_method_on_skeleton_update: .. rst-class:: classref-method -|void| **set_use_external_skeleton**\ (\ use_external_skeleton\: :ref:`bool`\ ) +|void| **on_skeleton_update**\ (\ ) :ref:`🔗` -Sets whether the BoneAttachment3D node will use an external :ref:`Skeleton3D` node rather than attempting to use its parent node as the :ref:`Skeleton3D`. When set to ``true``, the BoneAttachment3D node will use the external :ref:`Skeleton3D` node set in :ref:`set_external_skeleton`. +A function that is called automatically when the :ref:`Skeleton3D` is updated. This function is where the **BoneAttachment3D** node updates its position so it is correctly bound when it is *not* set to override the bone pose. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_boneconstraint3d.rst b/classes/class_boneconstraint3d.rst new file mode 100644 index 00000000000..95c4d77aba0 --- /dev/null +++ b/classes/class_boneconstraint3d.rst @@ -0,0 +1,239 @@ +: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/BoneConstraint3D.xml. + +.. _class_BoneConstraint3D: + +BoneConstraint3D +================ + +**Inherits:** :ref:`SkeletonModifier3D` **<** :ref:`Node3D` **<** :ref:`Node` **<** :ref:`Object` + +**Inherited By:** :ref:`AimModifier3D`, :ref:`ConvertTransformModifier3D`, :ref:`CopyTransformModifier3D` + +A node that may modify Skeleton3D's bone with associating the two bones. + +.. rst-class:: classref-introduction-group + +Description +----------- + +Base class of :ref:`SkeletonModifier3D` that modifies the bone set in :ref:`set_apply_bone()` based on the transform of the bone retrieved by :ref:`get_reference_bone()`. + +.. rst-class:: classref-reftable-group + +Methods +------- + +.. table:: + :widths: auto + + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear_setting`\ (\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_amount`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_apply_bone`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_apply_bone_name`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_reference_bone`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_reference_bone_name`\ (\ index\: :ref:`int`\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_setting_count`\ (\ ) |const| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_amount`\ (\ index\: :ref:`int`, amount\: :ref:`float`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_apply_bone`\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_apply_bone_name`\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_reference_bone`\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_reference_bone_name`\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_setting_count`\ (\ count\: :ref:`int`\ ) | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Method Descriptions +------------------- + +.. _class_BoneConstraint3D_method_clear_setting: + +.. rst-class:: classref-method + +|void| **clear_setting**\ (\ ) :ref:`🔗` + +Clear all settings. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_amount: + +.. rst-class:: classref-method + +:ref:`float` **get_amount**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the apply amount of the setting at ``index``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_apply_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_apply_bone**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the apply bone of the setting at ``index``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_apply_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_apply_bone_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the apply bone name of the setting at ``index``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_reference_bone: + +.. rst-class:: classref-method + +:ref:`int` **get_reference_bone**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the reference bone of the setting at ``index``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_reference_bone_name: + +.. rst-class:: classref-method + +:ref:`String` **get_reference_bone_name**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns the reference bone name of the setting at ``index``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_get_setting_count: + +.. rst-class:: classref-method + +:ref:`int` **get_setting_count**\ (\ ) |const| :ref:`🔗` + +Returns the number of settings in the modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_amount: + +.. rst-class:: classref-method + +|void| **set_amount**\ (\ index\: :ref:`int`, amount\: :ref:`float`\ ) :ref:`🔗` + +Sets the apply amount of the setting at ``index`` to ``amount``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_apply_bone: + +.. rst-class:: classref-method + +|void| **set_apply_bone**\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) :ref:`🔗` + +Sets the apply bone of the setting at ``index`` to ``bone``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_apply_bone_name: + +.. rst-class:: classref-method + +|void| **set_apply_bone_name**\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) :ref:`🔗` + +Sets the apply bone of the setting at ``index`` to ``bone_name``. This bone will be modified. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_reference_bone: + +.. rst-class:: classref-method + +|void| **set_reference_bone**\ (\ index\: :ref:`int`, bone\: :ref:`int`\ ) :ref:`🔗` + +Sets the reference bone of the setting at ``index`` to ``bone``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_reference_bone_name: + +.. rst-class:: classref-method + +|void| **set_reference_bone_name**\ (\ index\: :ref:`int`, bone_name\: :ref:`String`\ ) :ref:`🔗` + +Sets the reference bone of the setting at ``index`` to ``bone_name``. + +This bone will be only referenced and not modified by this modifier. + +.. rst-class:: classref-item-separator + +---- + +.. _class_BoneConstraint3D_method_set_setting_count: + +.. rst-class:: classref-method + +|void| **set_setting_count**\ (\ count\: :ref:`int`\ ) :ref:`🔗` + +Sets the number of settings in the modifier. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_bonemap.rst b/classes/class_bonemap.rst index b9b2d211930..c359e3aace2 100644 --- a/classes/class_bonemap.rst +++ b/classes/class_bonemap.rst @@ -71,7 +71,7 @@ Signals .. rst-class:: classref-signal -**bone_map_updated**\ (\ ) +**bone_map_updated**\ (\ ) :ref:`🔗` This signal is emitted when change the key value in the **BoneMap**. This is used to validate mapping and to update **BoneMap** editor. @@ -83,7 +83,7 @@ This signal is emitted when change the key value in the **BoneMap**. This is use .. rst-class:: classref-signal -**profile_updated**\ (\ ) +**profile_updated**\ (\ ) :ref:`🔗` This signal is emitted when change the value in profile or change the reference of profile. This is used to update key names in the **BoneMap** and to redraw the **BoneMap** editor. @@ -100,7 +100,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`SkeletonProfile` **profile** +:ref:`SkeletonProfile` **profile** :ref:`🔗` .. rst-class:: classref-property-setget @@ -122,7 +122,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`StringName` **find_profile_bone_name**\ (\ skeleton_bone_name\: :ref:`StringName`\ ) |const| +:ref:`StringName` **find_profile_bone_name**\ (\ skeleton_bone_name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns a profile bone name having ``skeleton_bone_name``. If not found, an empty :ref:`StringName` will be returned. @@ -136,7 +136,7 @@ In the retargeting process, the returned bone name is the bone name of the targe .. rst-class:: classref-method -:ref:`StringName` **get_skeleton_bone_name**\ (\ profile_bone_name\: :ref:`StringName`\ ) |const| +:ref:`StringName` **get_skeleton_bone_name**\ (\ profile_bone_name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns a skeleton bone name is mapped to ``profile_bone_name``. @@ -150,13 +150,14 @@ In the retargeting process, the returned bone name is the bone name of the sourc .. rst-class:: classref-method -|void| **set_skeleton_bone_name**\ (\ profile_bone_name\: :ref:`StringName`, skeleton_bone_name\: :ref:`StringName`\ ) +|void| **set_skeleton_bone_name**\ (\ profile_bone_name\: :ref:`StringName`, skeleton_bone_name\: :ref:`StringName`\ ) :ref:`🔗` Maps a skeleton bone name to ``profile_bone_name``. In the retargeting process, the setting bone name is the bone name of the source skeleton. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_bool.rst b/classes/class_bool.rst index 11cad195b4f..19d783fef37 100644 --- a/classes/class_bool.rst +++ b/classes/class_bool.rst @@ -51,7 +51,7 @@ Booleans can be combined with the logical operators ``and``, ``or``, ``not`` to if bullets > 0 and not is_reloading(): launch_bullet() - + if bullets == 0 or is_reloading(): play_clack_sound() @@ -61,7 +61,7 @@ Booleans can be combined with the logical operators ``and``, ``or``, ``not`` to { LaunchBullet(); } - + if (bullets == 0 || IsReloading()) { PlayClackSound(); @@ -71,7 +71,7 @@ Booleans can be combined with the logical operators ``and``, ``or``, ``not`` to \ **Note:** In modern programming languages, logical operators are evaluated in order. All remaining conditions are skipped if their result would have no effect on the final value. This concept is known as `short-circuit evaluation `__ and can be useful to avoid evaluating expensive conditions in some performance-critical cases. -\ **Note:** By convention, built-in methods and properties that return booleans are usually defined as yes-no questions, single adjectives, or similar (:ref:`String.is_empty`, :ref:`Node.can_process`, :ref:`Camera2D.enabled`, etc.). +\ **Note:** By convention, built-in methods and properties that return booleans are usually defined as yes-no questions, single adjectives, or similar (:ref:`String.is_empty()`, :ref:`Node.can_process()`, :ref:`Camera2D.enabled`, etc.). .. rst-class:: classref-reftable-group @@ -122,7 +122,7 @@ Constructor Descriptions .. rst-class:: classref-constructor -:ref:`bool` **bool**\ (\ ) +:ref:`bool` **bool**\ (\ ) :ref:`🔗` Constructs a **bool** set to ``false``. @@ -169,7 +169,7 @@ Operator Descriptions .. rst-class:: classref-operator -:ref:`bool` **operator !=**\ (\ right\: :ref:`bool`\ ) +:ref:`bool` **operator !=**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` Returns ``true`` if the two booleans are not equal. That is, one is ``true`` and the other is ``false``. This operation can be seen as a logical XOR. @@ -181,7 +181,7 @@ Returns ``true`` if the two booleans are not equal. That is, one is ``true`` and .. rst-class:: classref-operator -:ref:`bool` **operator <**\ (\ right\: :ref:`bool`\ ) +:ref:`bool` **operator <**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` Returns ``true`` if the left operand is ``false`` and the right operand is ``true``. @@ -193,7 +193,7 @@ Returns ``true`` if the left operand is ``false`` and the right operand is ``tru .. rst-class:: classref-operator -:ref:`bool` **operator ==**\ (\ right\: :ref:`bool`\ ) +:ref:`bool` **operator ==**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` Returns ``true`` if the two booleans are equal. That is, both are ``true`` or both are ``false``. This operation can be seen as a logical EQ or XNOR. @@ -205,11 +205,12 @@ Returns ``true`` if the two booleans are equal. That is, both are ``true`` or bo .. rst-class:: classref-operator -:ref:`bool` **operator >**\ (\ right\: :ref:`bool`\ ) +:ref:`bool` **operator >**\ (\ right\: :ref:`bool`\ ) :ref:`🔗` Returns ``true`` if the left operand is ``true`` and the right operand is ``false``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_boxcontainer.rst b/classes/class_boxcontainer.rst index 20336ea66ca..99dac8ba900 100644 --- a/classes/class_boxcontainer.rst +++ b/classes/class_boxcontainer.rst @@ -81,7 +81,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **AlignmentMode**: +enum **AlignmentMode**: :ref:`🔗` .. _class_BoxContainer_constant_ALIGNMENT_BEGIN: @@ -120,7 +120,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`AlignmentMode` **alignment** = ``0`` +:ref:`AlignmentMode` **alignment** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -137,7 +137,7 @@ The alignment of the container's children (must be one of :ref:`ALIGNMENT_BEGIN< .. rst-class:: classref-property -:ref:`bool` **vertical** = ``false`` +:ref:`bool` **vertical** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -161,7 +161,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Control` **add_spacer**\ (\ begin\: :ref:`bool`\ ) +:ref:`Control` **add_spacer**\ (\ begin\: :ref:`bool`\ ) :ref:`🔗` Adds a :ref:`Control` node to the box as a spacer. If ``begin`` is ``true``, it will insert the :ref:`Control` node in front of all other children. @@ -178,11 +178,12 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`int` **separation** = ``4`` +:ref:`int` **separation** = ``4`` :ref:`🔗` The space between the **BoxContainer**'s elements, in pixels. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_boxmesh.rst b/classes/class_boxmesh.rst index 164246af107..7c9c8c44bf6 100644 --- a/classes/class_boxmesh.rst +++ b/classes/class_boxmesh.rst @@ -56,7 +56,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` +:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -73,7 +73,7 @@ The box's width, height and depth. .. rst-class:: classref-property -:ref:`int` **subdivide_depth** = ``0`` +:ref:`int` **subdivide_depth** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -90,7 +90,7 @@ Number of extra edge loops inserted along the Z axis. .. rst-class:: classref-property -:ref:`int` **subdivide_height** = ``0`` +:ref:`int` **subdivide_height** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -107,7 +107,7 @@ Number of extra edge loops inserted along the Y axis. .. rst-class:: classref-property -:ref:`int` **subdivide_width** = ``0`` +:ref:`int` **subdivide_width** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -117,6 +117,7 @@ Number of extra edge loops inserted along the Y axis. Number of extra edge loops inserted along the X axis. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_boxoccluder3d.rst b/classes/class_boxoccluder3d.rst index 80a543dcb31..6bb59fc0b93 100644 --- a/classes/class_boxoccluder3d.rst +++ b/classes/class_boxoccluder3d.rst @@ -55,7 +55,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` +:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -65,6 +65,7 @@ Property Descriptions The box's size in 3D units. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_boxshape3d.rst b/classes/class_boxshape3d.rst index 00aecb2cb3c..7e4eacc12c0 100644 --- a/classes/class_boxshape3d.rst +++ b/classes/class_boxshape3d.rst @@ -28,11 +28,11 @@ A 3D box shape, intended for use in physics. Usually used to provide a shape for Tutorials --------- -- `3D Physics Tests Demo `__ +- `3D Physics Tests Demo `__ -- `3D Kinematic Character Demo `__ +- `3D Kinematic Character Demo `__ -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ .. rst-class:: classref-reftable-group @@ -59,7 +59,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` +:ref:`Vector3` **size** = ``Vector3(1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -69,6 +69,7 @@ Property Descriptions The box's width, height and depth. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_button.rst b/classes/class_button.rst index 64d21a7e246..ac36fa9c325 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -23,7 +23,7 @@ Description **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:**\ +\ **Example:** Create a button and connect a method that will be called when the button is pressed: .. tabs:: @@ -33,9 +33,9 @@ Description func _ready(): var button = Button.new() button.text = "Click me" - button.pressed.connect(self._button_pressed) + button.pressed.connect(_button_pressed) add_child(button) - + func _button_pressed(): print("Hello world!") @@ -48,7 +48,7 @@ Description button.Pressed += ButtonPressed; AddChild(button); } - + private void ButtonPressed() { GD.Print("Hello world!"); @@ -58,16 +58,16 @@ Description 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. +\ **Note:** Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions. .. rst-class:: classref-introduction-group Tutorials --------- -- `2D Dodge The Creeps Demo `__ +- `2D Dodge The Creeps Demo `__ -- `OS Test Demo `__ +- `Operating System Testing Demo `__ .. rst-class:: classref-reftable-group @@ -82,6 +82,8 @@ Properties +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`AutowrapMode` | :ref:`autowrap_mode` | ``0`` | +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ + | |bitfield|\[:ref:`LineBreakFlag`\] | :ref:`autowrap_trim_flags` | ``128`` | + +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`clip_text` | ``false`` | +-------------------------------------------------------------------+-------------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`expand_icon` | ``false`` | @@ -111,67 +113,71 @@ Theme Properties .. table:: :widths: auto - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_color` | ``Color(0.875, 0.875, 0.875, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_disabled_color` | ``Color(0.875, 0.875, 0.875, 0.5)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_focus_color` | ``Color(0.95, 0.95, 0.95, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_hover_color` | ``Color(0.95, 0.95, 0.95, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_hover_pressed_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_outline_color` | ``Color(0, 0, 0, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`font_pressed_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`icon_disabled_color` | ``Color(1, 1, 1, 0.4)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`icon_focus_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`icon_hover_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`icon_hover_pressed_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`icon_normal_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Color` | :ref:`icon_pressed_color` | ``Color(1, 1, 1, 1)`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`int` | :ref:`h_separation` | ``4`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`int` | :ref:`icon_max_width` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`int` | :ref:`outline_size` | ``0`` | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Font` | :ref:`font` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`int` | :ref:`font_size` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`Texture2D` | :ref:`icon` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`disabled` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`disabled_mirrored` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`focus` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`hover` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`hover_mirrored` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`hover_pressed` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`hover_pressed_mirrored` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`normal` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`normal_mirrored` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`pressed` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ - | :ref:`StyleBox` | :ref:`pressed_mirrored` | | - +-----------------------------------+------------------------------------------------------------------------------------+-------------------------------------+ + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_color` | ``Color(0.875, 0.875, 0.875, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_disabled_color` | ``Color(0.875, 0.875, 0.875, 0.5)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_focus_color` | ``Color(0.95, 0.95, 0.95, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_hover_color` | ``Color(0.95, 0.95, 0.95, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_hover_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_outline_color` | ``Color(0, 0, 0, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`font_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_disabled_color` | ``Color(1, 1, 1, 0.4)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_focus_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_hover_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_hover_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_normal_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Color` | :ref:`icon_pressed_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`align_to_largest_stylebox` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`h_separation` | ``4`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`icon_max_width` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`line_spacing` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`outline_size` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Font` | :ref:`font` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`font_size` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`Texture2D` | :ref:`icon` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`disabled` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`disabled_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`focus` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover_pressed` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`hover_pressed_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`normal` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`normal_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`pressed` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`StyleBox` | :ref:`pressed_mirrored` | | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ .. rst-class:: classref-section-separator @@ -186,14 +192,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`HorizontalAlignment` **alignment** = ``1`` +:ref:`HorizontalAlignment` **alignment** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_text_alignment**\ (\ value\: :ref:`HorizontalAlignment`\ ) - :ref:`HorizontalAlignment` **get_text_alignment**\ (\ ) -Text alignment policy for the button's text, use one of the :ref:`HorizontalAlignment` constants. +Text alignment policy for the button's text. .. rst-class:: classref-item-separator @@ -203,7 +209,7 @@ Text alignment policy for the button's text, use one of the :ref:`HorizontalAlig .. rst-class:: classref-property -:ref:`AutowrapMode` **autowrap_mode** = ``0`` +:ref:`AutowrapMode` **autowrap_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -216,18 +222,35 @@ If set to something other than :ref:`TextServer.AUTOWRAP_OFF`\] **autowrap_trim_flags** = ``128`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_autowrap_trim_flags**\ (\ value\: |bitfield|\[:ref:`LineBreakFlag`\]\ ) +- |bitfield|\[:ref:`LineBreakFlag`\] **get_autowrap_trim_flags**\ (\ ) + +Autowrap space trimming flags. See :ref:`TextServer.BREAK_TRIM_START_EDGE_SPACES` and :ref:`TextServer.BREAK_TRIM_END_EDGE_SPACES` for more info. + +.. rst-class:: classref-item-separator + +---- + .. _class_Button_property_clip_text: .. rst-class:: classref-property -:ref:`bool` **clip_text** = ``false`` +:ref:`bool` **clip_text** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_clip_text**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_clip_text**\ (\ ) -When this property is enabled, text that is too large to fit the button is clipped, when disabled the Button will always be wide enough to hold the text. +If ``true``, text that is too large to fit the button is clipped horizontally. If ``false``, the button will always be wide enough to hold the text. The text is not vertically clipped, and the button's height is not affected by this property. .. rst-class:: classref-item-separator @@ -237,7 +260,7 @@ When this property is enabled, text that is too large to fit the button is clipp .. rst-class:: classref-property -:ref:`bool` **expand_icon** = ``false`` +:ref:`bool` **expand_icon** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -254,7 +277,7 @@ When enabled, the button's icon will expand/shrink to fit the button's size whil .. rst-class:: classref-property -:ref:`bool` **flat** = ``false`` +:ref:`bool` **flat** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -271,7 +294,7 @@ Flat buttons don't display decoration. .. rst-class:: classref-property -:ref:`Texture2D` **icon** +:ref:`Texture2D` **icon** :ref:`🔗` .. rst-class:: classref-property-setget @@ -290,7 +313,7 @@ To edit margin and spacing of the icon, use :ref:`h_separation` **icon_alignment** = ``0`` +:ref:`HorizontalAlignment` **icon_alignment** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -307,7 +330,7 @@ Specifies if the icon should be aligned horizontally to the left, right, or cent .. rst-class:: classref-property -:ref:`String` **language** = ``""`` +:ref:`String` **language** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -324,7 +347,7 @@ Language code used for line-breaking and text shaping algorithms, if left empty .. rst-class:: classref-property -:ref:`String` **text** = ``""`` +:ref:`String` **text** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -341,7 +364,7 @@ The button's text that will be displayed inside the button's area. .. rst-class:: classref-property -:ref:`TextDirection` **text_direction** = ``0`` +:ref:`TextDirection` **text_direction** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -358,14 +381,14 @@ Base text writing direction. .. rst-class:: classref-property -:ref:`OverrunBehavior` **text_overrun_behavior** = ``0`` +:ref:`OverrunBehavior` **text_overrun_behavior** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_text_overrun_behavior**\ (\ value\: :ref:`OverrunBehavior`\ ) - :ref:`OverrunBehavior` **get_text_overrun_behavior**\ (\ ) -Sets the clipping behavior when the text exceeds the node's bounding rectangle. See :ref:`OverrunBehavior` for a description of all modes. +Sets the clipping behavior when the text exceeds the node's bounding rectangle. .. rst-class:: classref-item-separator @@ -375,7 +398,7 @@ Sets the clipping behavior when the text exceeds the node's bounding rectangle. .. rst-class:: classref-property -:ref:`VerticalAlignment` **vertical_icon_alignment** = ``1`` +:ref:`VerticalAlignment` **vertical_icon_alignment** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -397,7 +420,7 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Color` **font_color** = ``Color(0.875, 0.875, 0.875, 1)`` +:ref:`Color` **font_color** = ``Color(0.875, 0.875, 0.875, 1)`` :ref:`🔗` Default text :ref:`Color` of the **Button**. @@ -409,7 +432,7 @@ Default text :ref:`Color` of the **Button**. .. rst-class:: classref-themeproperty -:ref:`Color` **font_disabled_color** = ``Color(0.875, 0.875, 0.875, 0.5)`` +:ref:`Color` **font_disabled_color** = ``Color(0.875, 0.875, 0.875, 0.5)`` :ref:`🔗` Text :ref:`Color` used when the **Button** is disabled. @@ -421,7 +444,7 @@ Text :ref:`Color` used when the **Button** is disabled. .. rst-class:: classref-themeproperty -:ref:`Color` **font_focus_color** = ``Color(0.95, 0.95, 0.95, 1)`` +:ref:`Color` **font_focus_color** = ``Color(0.95, 0.95, 0.95, 1)`` :ref:`🔗` Text :ref:`Color` used when the **Button** is focused. Only replaces the normal text color of the button. Disabled, hovered, and pressed states take precedence over this color. @@ -433,7 +456,7 @@ Text :ref:`Color` used when the **Button** is focused. Only replace .. rst-class:: classref-themeproperty -:ref:`Color` **font_hover_color** = ``Color(0.95, 0.95, 0.95, 1)`` +:ref:`Color` **font_hover_color** = ``Color(0.95, 0.95, 0.95, 1)`` :ref:`🔗` Text :ref:`Color` used when the **Button** is being hovered. @@ -445,7 +468,7 @@ Text :ref:`Color` used when the **Button** is being hovered. .. rst-class:: classref-themeproperty -:ref:`Color` **font_hover_pressed_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **font_hover_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Text :ref:`Color` used when the **Button** is being hovered and pressed. @@ -457,7 +480,7 @@ Text :ref:`Color` used when the **Button** is being hovered and pre .. rst-class:: classref-themeproperty -:ref:`Color` **font_outline_color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **font_outline_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` The tint of text outline of the **Button**. @@ -469,7 +492,7 @@ The tint of text outline of the **Button**. .. rst-class:: classref-themeproperty -:ref:`Color` **font_pressed_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **font_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Text :ref:`Color` used when the **Button** is being pressed. @@ -481,7 +504,7 @@ Text :ref:`Color` used when the **Button** is being pressed. .. rst-class:: classref-themeproperty -:ref:`Color` **icon_disabled_color** = ``Color(1, 1, 1, 0.4)`` +:ref:`Color` **icon_disabled_color** = ``Color(1, 1, 1, 0.4)`` :ref:`🔗` Icon modulate :ref:`Color` used when the **Button** is disabled. @@ -493,7 +516,7 @@ Icon modulate :ref:`Color` used when the **Button** is disabled. .. rst-class:: classref-themeproperty -:ref:`Color` **icon_focus_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **icon_focus_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Icon modulate :ref:`Color` used when the **Button** is focused. Only replaces the normal modulate color of the button. Disabled, hovered, and pressed states take precedence over this color. @@ -505,7 +528,7 @@ Icon modulate :ref:`Color` used when the **Button** is focused. Onl .. rst-class:: classref-themeproperty -:ref:`Color` **icon_hover_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **icon_hover_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Icon modulate :ref:`Color` used when the **Button** is being hovered. @@ -517,7 +540,7 @@ Icon modulate :ref:`Color` used when the **Button** is being hovere .. rst-class:: classref-themeproperty -:ref:`Color` **icon_hover_pressed_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **icon_hover_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Icon modulate :ref:`Color` used when the **Button** is being hovered and pressed. @@ -529,7 +552,7 @@ Icon modulate :ref:`Color` used when the **Button** is being hovere .. rst-class:: classref-themeproperty -:ref:`Color` **icon_normal_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **icon_normal_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Default icon modulate :ref:`Color` of the **Button**. @@ -541,7 +564,7 @@ Default icon modulate :ref:`Color` of the **Button**. .. rst-class:: classref-themeproperty -:ref:`Color` **icon_pressed_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **icon_pressed_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` Icon modulate :ref:`Color` used when the **Button** is being pressed. @@ -549,11 +572,23 @@ Icon modulate :ref:`Color` used when the **Button** is being presse ---- +.. _class_Button_theme_constant_align_to_largest_stylebox: + +.. rst-class:: classref-themeproperty + +:ref:`int` **align_to_largest_stylebox** = ``0`` :ref:`🔗` + +This constant acts as a boolean. If ``true``, the minimum size of the button and text/icon alignment is always based on the largest stylebox margins, otherwise it's based on the current button state stylebox margins. + +.. rst-class:: classref-item-separator + +---- + .. _class_Button_theme_constant_h_separation: .. rst-class:: classref-themeproperty -:ref:`int` **h_separation** = ``4`` +:ref:`int` **h_separation** = ``4`` :ref:`🔗` The horizontal space between **Button**'s icon and text. Negative values will be treated as ``0`` when used. @@ -565,9 +600,21 @@ The horizontal space between **Button**'s icon and text. Negative values will be .. rst-class:: classref-themeproperty -:ref:`int` **icon_max_width** = ``0`` +:ref:`int` **icon_max_width** = ``0`` :ref:`🔗` + +The maximum allowed width of the **Button**'s icon. This limit is applied on top of the default size of the icon, or its expanded size if :ref:`expand_icon` is ``true``. The height is adjusted according to the icon's ratio. If the button has additional icons (e.g. :ref:`CheckBox`), they will also be limited. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Button_theme_constant_line_spacing: + +.. rst-class:: classref-themeproperty + +:ref:`int` **line_spacing** = ``0`` :ref:`🔗` -The maximum allowed width of the **Button**'s icon. This limit is applied on top of the default size of the icon, or its expanded size if :ref:`expand_icon` is ``true``. The height is adjusted according to the icon's ratio. +Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. .. rst-class:: classref-item-separator @@ -577,7 +624,7 @@ The maximum allowed width of the **Button**'s icon. This limit is applied on top .. rst-class:: classref-themeproperty -:ref:`int` **outline_size** = ``0`` +:ref:`int` **outline_size** = ``0`` :ref:`🔗` The size of the text outline. @@ -591,7 +638,7 @@ The size of the text outline. .. rst-class:: classref-themeproperty -:ref:`Font` **font** +:ref:`Font` **font** :ref:`🔗` :ref:`Font` of the **Button**'s text. @@ -603,7 +650,7 @@ The size of the text outline. .. rst-class:: classref-themeproperty -:ref:`int` **font_size** +:ref:`int` **font_size** :ref:`🔗` Font size of the **Button**'s text. @@ -615,7 +662,7 @@ Font size of the **Button**'s text. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **icon** +:ref:`Texture2D` **icon** :ref:`🔗` Default icon for the **Button**. Appears only if :ref:`icon` is not assigned. @@ -627,7 +674,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **disabled** +:ref:`StyleBox` **disabled** :ref:`🔗` :ref:`StyleBox` used when the **Button** is disabled. @@ -639,7 +686,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **disabled_mirrored** +:ref:`StyleBox` **disabled_mirrored** :ref:`🔗` :ref:`StyleBox` used when the **Button** is disabled (for right-to-left layouts). @@ -651,7 +698,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **focus** +:ref:`StyleBox` **focus** :ref:`🔗` :ref:`StyleBox` used when the **Button** is focused. The :ref:`focus` :ref:`StyleBox` is displayed *over* the base :ref:`StyleBox`, so a partially transparent :ref:`StyleBox` should be used to ensure the base :ref:`StyleBox` remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. @@ -663,7 +710,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **hover** +:ref:`StyleBox` **hover** :ref:`🔗` :ref:`StyleBox` used when the **Button** is being hovered. @@ -675,7 +722,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **hover_mirrored** +:ref:`StyleBox` **hover_mirrored** :ref:`🔗` :ref:`StyleBox` used when the **Button** is being hovered (for right-to-left layouts). @@ -687,7 +734,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **hover_pressed** +:ref:`StyleBox` **hover_pressed** :ref:`🔗` :ref:`StyleBox` used when the **Button** is being pressed and hovered at the same time. @@ -699,7 +746,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **hover_pressed_mirrored** +:ref:`StyleBox` **hover_pressed_mirrored** :ref:`🔗` :ref:`StyleBox` used when the **Button** is being pressed and hovered at the same time (for right-to-left layouts). @@ -711,7 +758,7 @@ Default icon for the **Button**. Appears only if :ref:`icon` **normal** +:ref:`StyleBox` **normal** :ref:`🔗` Default :ref:`StyleBox` for the **Button**. @@ -723,7 +770,7 @@ Default :ref:`StyleBox` for the **Button**. .. rst-class:: classref-themeproperty -:ref:`StyleBox` **normal_mirrored** +:ref:`StyleBox` **normal_mirrored** :ref:`🔗` Default :ref:`StyleBox` for the **Button** (for right-to-left layouts). @@ -735,7 +782,7 @@ Default :ref:`StyleBox` for the **Button** (for right-to-left la .. rst-class:: classref-themeproperty -:ref:`StyleBox` **pressed** +:ref:`StyleBox` **pressed** :ref:`🔗` :ref:`StyleBox` used when the **Button** is being pressed. @@ -747,11 +794,12 @@ Default :ref:`StyleBox` for the **Button** (for right-to-left la .. rst-class:: classref-themeproperty -:ref:`StyleBox` **pressed_mirrored** +:ref:`StyleBox` **pressed_mirrored** :ref:`🔗` :ref:`StyleBox` used when the **Button** is being pressed (for right-to-left layouts). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_buttongroup.rst b/classes/class_buttongroup.rst index 4b9a673c66e..ab41d271059 100644 --- a/classes/class_buttongroup.rst +++ b/classes/class_buttongroup.rst @@ -1,5 +1,8 @@ :github_url: hide +.. meta:: + :keywords: radio + .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. @@ -64,7 +67,7 @@ Signals .. rst-class:: classref-signal -**pressed**\ (\ button\: :ref:`BaseButton`\ ) +**pressed**\ (\ button\: :ref:`BaseButton`\ ) :ref:`🔗` Emitted when one of the buttons of the group is pressed. @@ -81,7 +84,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **allow_unpress** = ``false`` +:ref:`bool` **allow_unpress** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -103,7 +106,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Array`\[:ref:`BaseButton`\] **get_buttons**\ (\ ) +:ref:`Array`\[:ref:`BaseButton`\] **get_buttons**\ (\ ) :ref:`🔗` Returns an :ref:`Array` of :ref:`Button`\ s who have this as their **ButtonGroup** (see :ref:`BaseButton.button_group`). @@ -115,11 +118,12 @@ Returns an :ref:`Array` of :ref:`Button`\ s who have .. rst-class:: classref-method -:ref:`BaseButton` **get_pressed_button**\ (\ ) +:ref:`BaseButton` **get_pressed_button**\ (\ ) :ref:`🔗` Returns the current pressed button. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 0d26b3e85b9..9ad65d199a5 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -17,9 +17,7 @@ A built-in type representing a method or a standalone function. Description ----------- -**Callable** is a built-in :ref:`Variant` type that represents a function. It can either be a method within an :ref:`Object` instance, or a custom callable used for different purposes (see :ref:`is_custom`). Like all :ref:`Variant` types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. - -\ **Example:**\ +**Callable** is a built-in :ref:`Variant` type that represents a function. It can either be a method within an :ref:`Object` instance, or a custom callable used for different purposes (see :ref:`is_custom()`). Like all :ref:`Variant` types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. .. tabs:: @@ -28,11 +26,11 @@ Description func print_args(arg1, arg2, arg3 = ""): prints(arg1, arg2, arg3) - + func test(): var callable = Callable(self, "print_args") callable.call("hello", "world") # Prints "hello world ". - callable.call(Vector2.UP, 42, callable) # Prints "(0, -1) 42 Node(node.gd)::print_args". + callable.call(Vector2.UP, 42, callable) # Prints "(0.0, -1.0) 42 Node(node.gd)::print_args" callable.call("invalid") # Invalid call, should have at least 2 arguments. .. code-tab:: csharp @@ -42,29 +40,29 @@ Description { GD.PrintS(arg1, arg2, arg3); } - + public void Test() { // Invalid calls fail silently. Callable callable = new Callable(this, MethodName.PrintArgs); callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments. - callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs". + callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs" callable.Call("invalid"); // Invalid call, should have 3 arguments. } -In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an :ref:`Object` instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling :ref:`get_method`. +In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an :ref:`Object` instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling :ref:`get_method()`. :: func _init(): var my_lambda = func (message): print(message) - - # Prints Hello everyone! + + # Prints "Hello everyone!" my_lambda.call("Hello everyone!") - + # Prints "Attack!", when the button_pressed signal is emitted. button_pressed.connect(func(): print("Attack!")) @@ -80,11 +78,11 @@ In GDScript, you can access methods and global functions as **Callable**\ s: :: - var dictionary = {"hello": "world"} - + var dictionary = { "hello": "world" } + # This will not work, `clear` is treated as a key. tween.tween_callback(dictionary.clear) - + # This will work. tween.tween_callback(Callable.create(dictionary, "clear")) @@ -129,6 +127,8 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Callable` | :ref:`create`\ (\ variant\: :ref:`Variant`, method\: :ref:`StringName`\ ) |static| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_argument_count`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`get_bound_arguments`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_bound_arguments_count`\ (\ ) |const| | @@ -139,6 +139,8 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_object_id`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_unbound_arguments_count`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`hash`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_custom`\ (\ ) |const| | @@ -183,7 +185,7 @@ Constructor Descriptions .. rst-class:: classref-constructor -:ref:`Callable` **Callable**\ (\ ) +:ref:`Callable` **Callable**\ (\ ) :ref:`🔗` Constructs an empty **Callable**, with no object nor method bound. @@ -207,7 +209,7 @@ Constructs a **Callable** as a copy of the given **Callable**. Creates a new **Callable** for the method named ``method`` in the specified ``object``. -\ **Note:** For methods of built-in :ref:`Variant` types, use :ref:`create` instead. +\ **Note:** For methods of built-in :ref:`Variant` types, use :ref:`create()` instead. .. rst-class:: classref-section-separator @@ -222,9 +224,9 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Callable` **bind**\ (\ ...\ ) |vararg| |const| +:ref:`Callable` **bind**\ (\ ...\ ) |vararg| |const| :ref:`🔗` -Returns a copy of this **Callable** with one or more arguments bound. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call`. See also :ref:`unbind`. +Returns a copy of this **Callable** with one or more arguments bound. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call()`. See also :ref:`unbind()`. \ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. @@ -236,9 +238,9 @@ Returns a copy of this **Callable** with one or more arguments bound. When calle .. rst-class:: classref-method -:ref:`Callable` **bindv**\ (\ arguments\: :ref:`Array`\ ) +:ref:`Callable` **bindv**\ (\ arguments\: :ref:`Array`\ ) :ref:`🔗` -Returns a copy of this **Callable** with one or more arguments bound, reading them from an array. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call`. See also :ref:`unbind`. +Returns a copy of this **Callable** with one or more arguments bound, reading them from an array. When called, the bound arguments are passed *after* the arguments supplied by :ref:`call()`. See also :ref:`unbind()`. \ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. @@ -250,7 +252,7 @@ Returns a copy of this **Callable** with one or more arguments bound, reading th .. rst-class:: classref-method -:ref:`Variant` **call**\ (\ ...\ ) |vararg| |const| +:ref:`Variant` **call**\ (\ ...\ ) |vararg| |const| :ref:`🔗` Calls the method represented by this **Callable**. Arguments can be passed and should match the method's signature. @@ -262,7 +264,7 @@ Calls the method represented by this **Callable**. Arguments can be passed and s .. rst-class:: classref-method -|void| **call_deferred**\ (\ ...\ ) |vararg| |const| +|void| **call_deferred**\ (\ ...\ ) |vararg| |const| :ref:`🔗` Calls the method represented by this **Callable** in deferred mode, i.e. at the end of the current frame. Arguments can be passed and should match the method's signature. @@ -285,7 +287,7 @@ Calls the method represented by this **Callable** in deferred mode, i.e. at the \ **Note:** Deferred calls are processed at idle time. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly. -See also :ref:`Object.call_deferred`. +See also :ref:`Object.call_deferred()`. .. rst-class:: classref-item-separator @@ -295,9 +297,9 @@ See also :ref:`Object.call_deferred`. .. rst-class:: classref-method -:ref:`Variant` **callv**\ (\ arguments\: :ref:`Array`\ ) |const| +:ref:`Variant` **callv**\ (\ arguments\: :ref:`Array`\ ) |const| :ref:`🔗` -Calls the method represented by this **Callable**. Unlike :ref:`call`, this method expects all arguments to be contained inside the ``arguments`` :ref:`Array`. +Calls the method represented by this **Callable**. Unlike :ref:`call()`, this method expects all arguments to be contained inside the ``arguments`` :ref:`Array`. .. rst-class:: classref-item-separator @@ -307,9 +309,9 @@ Calls the method represented by this **Callable**. Unlike :ref:`call` **create**\ (\ variant\: :ref:`Variant`, method\: :ref:`StringName`\ ) |static| +:ref:`Callable` **create**\ (\ variant\: :ref:`Variant`, method\: :ref:`StringName`\ ) |static| :ref:`🔗` -Creates a new **Callable** for the method named ``method`` in the specified ``variant``. To represent a method of a built-in :ref:`Variant` type, a custom callable is used (see :ref:`is_custom`). If ``variant`` is :ref:`Object`, then a standard callable will be created instead. +Creates a new **Callable** for the method named ``method`` in the specified ``variant``. To represent a method of a built-in :ref:`Variant` type, a custom callable is used (see :ref:`is_custom()`). If ``variant`` is :ref:`Object`, then a standard callable will be created instead. \ **Note:** This method is always necessary for the :ref:`Dictionary` type, as property syntax is used to access its entries. You may also use this method when ``variant``'s type is not known in advance (for polymorphism). @@ -317,13 +319,33 @@ Creates a new **Callable** for the method named ``method`` in the specified ``va ---- +.. _class_Callable_method_get_argument_count: + +.. rst-class:: classref-method + +:ref:`int` **get_argument_count**\ (\ ) |const| :ref:`🔗` + +Returns the total number of arguments this **Callable** should take, including optional arguments. This means that any arguments bound with :ref:`bind()` are *subtracted* from the result, and any arguments unbound with :ref:`unbind()` are *added* to the result. + +.. rst-class:: classref-item-separator + +---- + .. _class_Callable_method_get_bound_arguments: .. rst-class:: classref-method -:ref:`Array` **get_bound_arguments**\ (\ ) |const| +:ref:`Array` **get_bound_arguments**\ (\ ) |const| :ref:`🔗` + +Returns the array of arguments bound via successive :ref:`bind()` or :ref:`unbind()` calls. These arguments will be added *after* the arguments passed to the call, from which :ref:`get_unbound_arguments_count()` arguments on the right have been previously excluded. + +:: -Return the bound arguments (as long as :ref:`get_bound_arguments_count` is greater than zero), or empty (if :ref:`get_bound_arguments_count` is less than or equal to zero). + func get_effective_arguments(callable, call_args): + assert(call_args.size() - callable.get_unbound_arguments_count() >= 0) + var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count()) + result.append_array(callable.get_bound_arguments()) + return result .. rst-class:: classref-item-separator @@ -333,9 +355,11 @@ Return the bound arguments (as long as :ref:`get_bound_arguments_count` **get_bound_arguments_count**\ (\ ) |const| +:ref:`int` **get_bound_arguments_count**\ (\ ) |const| :ref:`🔗` -Returns the total amount of arguments bound (or unbound) via successive :ref:`bind` or :ref:`unbind` calls. If the amount of arguments unbound is greater than the ones bound, this function returns a value less than zero. +Returns the total amount of arguments bound via successive :ref:`bind()` or :ref:`unbind()` calls. This is the same as the size of the array returned by :ref:`get_bound_arguments()`. See :ref:`get_bound_arguments()` for details. + +\ **Note:** The :ref:`get_bound_arguments_count()` and :ref:`get_unbound_arguments_count()` methods can both return positive values. .. rst-class:: classref-item-separator @@ -345,7 +369,7 @@ Returns the total amount of arguments bound (or unbound) via successive :ref:`bi .. rst-class:: classref-method -:ref:`StringName` **get_method**\ (\ ) |const| +:ref:`StringName` **get_method**\ (\ ) |const| :ref:`🔗` Returns the name of the method represented by this **Callable**. If the callable is a GDScript lambda function, returns the function's name or ``""``. @@ -357,7 +381,7 @@ Returns the name of the method represented by this **Callable**. If the callable .. rst-class:: classref-method -:ref:`Object` **get_object**\ (\ ) |const| +:ref:`Object` **get_object**\ (\ ) |const| :ref:`🔗` Returns the object on which this **Callable** is called. @@ -369,9 +393,23 @@ Returns the object on which this **Callable** is called. .. rst-class:: classref-method -:ref:`int` **get_object_id**\ (\ ) |const| +:ref:`int` **get_object_id**\ (\ ) |const| :ref:`🔗` + +Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Callable_method_get_unbound_arguments_count: + +.. rst-class:: classref-method + +:ref:`int` **get_unbound_arguments_count**\ (\ ) |const| :ref:`🔗` -Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id`). +Returns the total amount of arguments unbound via successive :ref:`bind()` or :ref:`unbind()` calls. See :ref:`get_bound_arguments()` for details. + +\ **Note:** The :ref:`get_bound_arguments_count()` and :ref:`get_unbound_arguments_count()` methods can both return positive values. .. rst-class:: classref-item-separator @@ -381,11 +419,11 @@ Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id` **hash**\ (\ ) |const| +:ref:`int` **hash**\ (\ ) |const| :ref:`🔗` Returns the 32-bit hash value of this **Callable**'s object. -\ **Note:** **Callable**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for :ref:`hash`. +\ **Note:** **Callable**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for :ref:`hash()`. .. rst-class:: classref-item-separator @@ -395,13 +433,13 @@ Returns the 32-bit hash value of this **Callable**'s object. .. rst-class:: classref-method -:ref:`bool` **is_custom**\ (\ ) |const| +:ref:`bool` **is_custom**\ (\ ) |const| :ref:`🔗` Returns ``true`` if this **Callable** is a custom callable. Custom callables are used: -- for binding/unbinding arguments (see :ref:`bind` and :ref:`unbind`); +- for binding/unbinding arguments (see :ref:`bind()` and :ref:`unbind()`); -- for representing methods of built-in :ref:`Variant` types (see :ref:`create`); +- for representing methods of built-in :ref:`Variant` types (see :ref:`create()`); - for representing global, lambda, and RPC functions in GDScript; @@ -415,9 +453,11 @@ Returns ``true`` if this **Callable** is a custom callable. Custom callables are .. rst-class:: classref-method -:ref:`bool` **is_null**\ (\ ) |const| +:ref:`bool` **is_null**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if this **Callable** has no target to call the method on. Equivalent to ``callable == Callable()``. -Returns ``true`` if this **Callable** has no target to call the method on. +\ **Note:** This is *not* the same as ``not is_valid()`` and using ``not is_null()`` will *not* guarantee that this callable can be called. Use :ref:`is_valid()` instead. .. rst-class:: classref-item-separator @@ -427,9 +467,9 @@ Returns ``true`` if this **Callable** has no target to call the method on. .. rst-class:: classref-method -:ref:`bool` **is_standard**\ (\ ) |const| +:ref:`bool` **is_standard**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if this **Callable** is a standard callable. This method is the opposite of :ref:`is_custom`. Returns ``false`` if this callable is a lambda function. +Returns ``true`` if this **Callable** is a standard callable. This method is the opposite of :ref:`is_custom()`. Returns ``false`` if this callable is a lambda function. .. rst-class:: classref-item-separator @@ -439,7 +479,7 @@ Returns ``true`` if this **Callable** is a standard callable. This method is the .. rst-class:: classref-method -:ref:`bool` **is_valid**\ (\ ) |const| +:ref:`bool` **is_valid**\ (\ ) |const| :ref:`🔗` Returns ``true`` if the callable's object exists and has a valid method name assigned, or is a custom callable. @@ -451,9 +491,9 @@ Returns ``true`` if the callable's object exists and has a valid method name ass .. rst-class:: classref-method -|void| **rpc**\ (\ ...\ ) |vararg| |const| +|void| **rpc**\ (\ ...\ ) |vararg| |const| :ref:`🔗` -Perform an RPC (Remote Procedure Call) on all connected peers. This is used for multiplayer and is normally not available, unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc` or :ref:`Node.rpc_config`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc`. +Perform an RPC (Remote Procedure Call) on all connected peers. This is used for multiplayer and is normally not available, unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc` or :ref:`Node.rpc_config()`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc()`. .. rst-class:: classref-item-separator @@ -463,9 +503,9 @@ Perform an RPC (Remote Procedure Call) on all connected peers. This is used for .. rst-class:: classref-method -|void| **rpc_id**\ (\ peer_id\: :ref:`int`, ...\ ) |vararg| |const| +|void| **rpc_id**\ (\ peer_id\: :ref:`int`, ...\ ) |vararg| |const| :ref:`🔗` -Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc` or :ref:`Node.rpc_config`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc_id`. +Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as *RPC* (using :ref:`@GDScript.@rpc` or :ref:`Node.rpc_config()`). Calling this method on unsupported functions will result in an error. See :ref:`Node.rpc_id()`. .. rst-class:: classref-item-separator @@ -475,9 +515,9 @@ Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer do .. rst-class:: classref-method -:ref:`Callable` **unbind**\ (\ argcount\: :ref:`int`\ ) |const| +:ref:`Callable` **unbind**\ (\ argcount\: :ref:`int`\ ) |const| :ref:`🔗` -Returns a copy of this **Callable** with a number of arguments unbound. In other words, when the new callable is called the last few arguments supplied by the user are ignored, according to ``argcount``. The remaining arguments are passed to the callable. This allows to use the original callable in a context that attempts to pass more arguments than this callable can handle, e.g. a signal with a fixed number of arguments. See also :ref:`bind`. +Returns a copy of this **Callable** with a number of arguments unbound. In other words, when the new callable is called the last few arguments supplied by the user are ignored, according to ``argcount``. The remaining arguments are passed to the callable. This allows to use the original callable in a context that attempts to pass more arguments than this callable can handle, e.g. a signal with a fixed number of arguments. See also :ref:`bind()`. \ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. @@ -500,7 +540,7 @@ Operator Descriptions .. rst-class:: classref-operator -:ref:`bool` **operator !=**\ (\ right\: :ref:`Callable`\ ) +:ref:`bool` **operator !=**\ (\ right\: :ref:`Callable`\ ) :ref:`🔗` Returns ``true`` if both **Callable**\ s invoke different targets. @@ -512,11 +552,12 @@ Returns ``true`` if both **Callable**\ s invoke different targets. .. rst-class:: classref-operator -:ref:`bool` **operator ==**\ (\ right\: :ref:`Callable`\ ) +:ref:`bool` **operator ==**\ (\ right\: :ref:`Callable`\ ) :ref:`🔗` Returns ``true`` if both **Callable**\ s invoke the same custom target. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_callbacktweener.rst b/classes/class_callbacktweener.rst index 961111b782b..ce57848a558 100644 --- a/classes/class_callbacktweener.rst +++ b/classes/class_callbacktweener.rst @@ -19,11 +19,11 @@ Calls the specified method after optional delay. Description ----------- -**CallbackTweener** is used to call a method in a tweening sequence. See :ref:`Tween.tween_callback` for more usage information. +**CallbackTweener** is used to call a method in a tweening sequence. See :ref:`Tween.tween_callback()` for more usage information. The tweener will finish automatically if the callback's target object is freed. -\ **Note:** :ref:`Tween.tween_callback` is the only correct way to create **CallbackTweener**. Any **CallbackTweener** created manually will not function correctly. +\ **Note:** :ref:`Tween.tween_callback()` is the only correct way to create **CallbackTweener**. Any **CallbackTweener** created manually will not function correctly. .. rst-class:: classref-reftable-group @@ -50,18 +50,19 @@ Method Descriptions .. rst-class:: classref-method -:ref:`CallbackTweener` **set_delay**\ (\ delay\: :ref:`float`\ ) +:ref:`CallbackTweener` **set_delay**\ (\ delay\: :ref:`float`\ ) :ref:`🔗` Makes the callback call delayed by given time in seconds. -\ **Example:**\ +\ **Example:** Call :ref:`Node.queue_free()` after 2 seconds: :: var tween = get_tree().create_tween() - tween.tween_callback(queue_free).set_delay(2) #this will call queue_free() after 2 seconds + tween.tween_callback(queue_free).set_delay(2) .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_camera2d.rst b/classes/class_camera2d.rst index 9b02b053424..ef8d99ed917 100644 --- a/classes/class_camera2d.rst +++ b/classes/class_camera2d.rst @@ -23,20 +23,18 @@ Camera node for 2D scenes. It forces the screen (current layer) to scroll follow Cameras register themselves in the nearest :ref:`Viewport` node (when ascending the tree). Only one camera can be active per viewport. If no viewport is available ascending the tree, the camera will register in the global viewport. -This node is intended to be a simple helper to get things going quickly, but more functionality may be desired to change how the camera works. To make your own custom camera node, inherit it from :ref:`Node2D` and change the transform of the canvas by setting :ref:`Viewport.canvas_transform` in :ref:`Viewport` (you can obtain the current :ref:`Viewport` by using :ref:`Node.get_viewport`). +This node is intended to be a simple helper to get things going quickly, but more functionality may be desired to change how the camera works. To make your own custom camera node, inherit it from :ref:`Node2D` and change the transform of the canvas by setting :ref:`Viewport.canvas_transform` in :ref:`Viewport` (you can obtain the current :ref:`Viewport` by using :ref:`Node.get_viewport()`). -Note that the **Camera2D** node's ``position`` doesn't represent the actual position of the screen, which may differ due to applied smoothing or limits. You can use :ref:`get_screen_center_position` to get the real position. +Note that the **Camera2D** node's :ref:`Node2D.global_position` doesn't represent the actual position of the screen, which may differ due to applied smoothing or limits. You can use :ref:`get_screen_center_position()` to get the real position. Same for the node's :ref:`Node2D.global_rotation` which may be different due to applied rotation smoothing. You can use :ref:`get_screen_rotation()` to get the current rotation of the screen. .. rst-class:: classref-introduction-group Tutorials --------- -- `2D Platformer Demo `__ +- `2D Platformer Demo `__ -- `2D Isometric Demo `__ - -- `2D HDR Demo `__ +- `2D Isometric Demo `__ .. rst-class:: classref-reftable-group @@ -79,6 +77,8 @@ Properties +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ | :ref:`int` | :ref:`limit_bottom` | ``10000000`` | +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ + | :ref:`bool` | :ref:`limit_enabled` | ``true`` | + +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ | :ref:`int` | :ref:`limit_left` | ``-10000000`` | +-----------------------------------------------------------------------+---------------------------------------------------------------------------------------+-------------------+ | :ref:`int` | :ref:`limit_right` | ``10000000`` | @@ -121,6 +121,8 @@ Methods +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_screen_center_position`\ (\ ) |const| | +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_screen_rotation`\ (\ ) |const| | + +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_target_position`\ (\ ) |const| | +-------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_current`\ (\ ) |const| | @@ -147,7 +149,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **AnchorMode**: +enum **AnchorMode**: :ref:`🔗` .. _class_Camera2D_constant_ANCHOR_MODE_FIXED_TOP_LEFT: @@ -173,7 +175,7 @@ The camera's position takes into account vertical/horizontal offsets and the scr .. rst-class:: classref-enumeration -enum **Camera2DProcessCallback**: +enum **Camera2DProcessCallback**: :ref:`🔗` .. _class_Camera2D_constant_CAMERA2D_PROCESS_PHYSICS: @@ -204,14 +206,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`AnchorMode` **anchor_mode** = ``1`` +:ref:`AnchorMode` **anchor_mode** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_anchor_mode**\ (\ value\: :ref:`AnchorMode`\ ) - :ref:`AnchorMode` **get_anchor_mode**\ (\ ) -The Camera2D's anchor point. See :ref:`AnchorMode` constants. +The Camera2D's anchor point. .. rst-class:: classref-item-separator @@ -221,7 +223,7 @@ The Camera2D's anchor point. See :ref:`AnchorMode` con .. rst-class:: classref-property -:ref:`Node` **custom_viewport** +:ref:`Node` **custom_viewport** :ref:`🔗` .. rst-class:: classref-property-setget @@ -238,7 +240,7 @@ The custom :ref:`Viewport` node attached to the **Camera2D**. If .. rst-class:: classref-property -:ref:`float` **drag_bottom_margin** = ``0.2`` +:ref:`float` **drag_bottom_margin** = ``0.2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -255,7 +257,7 @@ Bottom margin needed to drag the camera. A value of ``1`` makes the camera move .. rst-class:: classref-property -:ref:`bool` **drag_horizontal_enabled** = ``false`` +:ref:`bool` **drag_horizontal_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -272,7 +274,7 @@ If ``true``, the camera only moves when reaching the horizontal (left and right) .. rst-class:: classref-property -:ref:`float` **drag_horizontal_offset** = ``0.0`` +:ref:`float` **drag_horizontal_offset** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -291,7 +293,7 @@ The relative horizontal drag offset of the camera between the right (``-1``) and .. rst-class:: classref-property -:ref:`float` **drag_left_margin** = ``0.2`` +:ref:`float` **drag_left_margin** = ``0.2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -308,7 +310,7 @@ Left margin needed to drag the camera. A value of ``1`` makes the camera move on .. rst-class:: classref-property -:ref:`float` **drag_right_margin** = ``0.2`` +:ref:`float` **drag_right_margin** = ``0.2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -325,7 +327,7 @@ Right margin needed to drag the camera. A value of ``1`` makes the camera move o .. rst-class:: classref-property -:ref:`float` **drag_top_margin** = ``0.2`` +:ref:`float` **drag_top_margin** = ``0.2`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -342,7 +344,7 @@ Top margin needed to drag the camera. A value of ``1`` makes the camera move onl .. rst-class:: classref-property -:ref:`bool` **drag_vertical_enabled** = ``false`` +:ref:`bool` **drag_vertical_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -359,7 +361,7 @@ If ``true``, the camera only moves when reaching the vertical (top and bottom) d .. rst-class:: classref-property -:ref:`float` **drag_vertical_offset** = ``0.0`` +:ref:`float` **drag_vertical_offset** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -378,7 +380,7 @@ The relative vertical drag offset of the camera between the bottom (``-1``) and .. rst-class:: classref-property -:ref:`bool` **editor_draw_drag_margin** = ``false`` +:ref:`bool` **editor_draw_drag_margin** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -395,7 +397,7 @@ If ``true``, draws the camera's drag margin rectangle in the editor. .. rst-class:: classref-property -:ref:`bool` **editor_draw_limits** = ``false`` +:ref:`bool` **editor_draw_limits** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -412,7 +414,7 @@ If ``true``, draws the camera's limits rectangle in the editor. .. rst-class:: classref-property -:ref:`bool` **editor_draw_screen** = ``true`` +:ref:`bool` **editor_draw_screen** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -429,14 +431,14 @@ If ``true``, draws the camera's screen rectangle in the editor. .. rst-class:: classref-property -:ref:`bool` **enabled** = ``true`` +:ref:`bool` **enabled** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_enabled**\ (\ ) -Controls whether the camera can be active or not. If ``true``, the **Camera2D** will become the main camera when it enters the scene tree and there is no active camera currently (see :ref:`Viewport.get_camera_2d`). +Controls whether the camera can be active or not. If ``true``, the **Camera2D** will become the main camera when it enters the scene tree and there is no active camera currently (see :ref:`Viewport.get_camera_2d()`). When the camera is currently active and :ref:`enabled` is set to ``false``, the next enabled **Camera2D** in the scene tree will become active. @@ -448,7 +450,7 @@ When the camera is currently active and :ref:`enabled` **ignore_rotation** = ``true`` +:ref:`bool` **ignore_rotation** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -465,7 +467,7 @@ If ``true``, the camera's rendered view is not affected by its :ref:`Node2D.rota .. rst-class:: classref-property -:ref:`int` **limit_bottom** = ``10000000`` +:ref:`int` **limit_bottom** = ``10000000`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -478,11 +480,28 @@ Bottom scroll limit in pixels. The camera stops moving when reaching this value, ---- +.. _class_Camera2D_property_limit_enabled: + +.. rst-class:: classref-property + +:ref:`bool` **limit_enabled** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_limit_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_limit_enabled**\ (\ ) + +If ``true``, the limits will be enabled. Disabling this will allow the camera to focus anywhere, when the four ``limit_*`` properties will not work. + +.. rst-class:: classref-item-separator + +---- + .. _class_Camera2D_property_limit_left: .. rst-class:: classref-property -:ref:`int` **limit_left** = ``-10000000`` +:ref:`int` **limit_left** = ``-10000000`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -499,7 +518,7 @@ Left scroll limit in pixels. The camera stops moving when reaching this value, b .. rst-class:: classref-property -:ref:`int` **limit_right** = ``10000000`` +:ref:`int` **limit_right** = ``10000000`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -516,7 +535,7 @@ Right scroll limit in pixels. The camera stops moving when reaching this value, .. rst-class:: classref-property -:ref:`bool` **limit_smoothed** = ``false`` +:ref:`bool` **limit_smoothed** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -527,7 +546,7 @@ If ``true``, the camera smoothly stops when reaches its limits. This property has no effect if :ref:`position_smoothing_enabled` is ``false``. -\ **Note:** To immediately update the camera's position to be within limits without smoothing, even with this setting enabled, invoke :ref:`reset_smoothing`. +\ **Note:** To immediately update the camera's position to be within limits without smoothing, even with this setting enabled, invoke :ref:`reset_smoothing()`. .. rst-class:: classref-item-separator @@ -537,7 +556,7 @@ This property has no effect if :ref:`position_smoothing_enabled` **limit_top** = ``-10000000`` +:ref:`int` **limit_top** = ``-10000000`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -554,7 +573,7 @@ Top scroll limit in pixels. The camera stops moving when reaching this value, bu .. rst-class:: classref-property -:ref:`Vector2` **offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -571,7 +590,7 @@ The camera's relative offset. Useful for looking around or camera shake animatio .. rst-class:: classref-property -:ref:`bool` **position_smoothing_enabled** = ``false`` +:ref:`bool` **position_smoothing_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -588,7 +607,7 @@ If ``true``, the camera's view smoothly moves towards its target position at :re .. rst-class:: classref-property -:ref:`float` **position_smoothing_speed** = ``5.0`` +:ref:`float` **position_smoothing_speed** = ``5.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -605,14 +624,14 @@ Speed in pixels per second of the camera's smoothing effect when :ref:`position_ .. rst-class:: classref-property -:ref:`Camera2DProcessCallback` **process_callback** = ``1`` +:ref:`Camera2DProcessCallback` **process_callback** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_process_callback**\ (\ value\: :ref:`Camera2DProcessCallback`\ ) - :ref:`Camera2DProcessCallback` **get_process_callback**\ (\ ) -The camera's process callback. See :ref:`Camera2DProcessCallback`. +The camera's process callback. .. rst-class:: classref-item-separator @@ -622,7 +641,7 @@ The camera's process callback. See :ref:`Camera2DProcessCallback` **rotation_smoothing_enabled** = ``false`` +:ref:`bool` **rotation_smoothing_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -641,7 +660,7 @@ If ``true``, the camera's view smoothly rotates, via asymptotic smoothing, to al .. rst-class:: classref-property -:ref:`float` **rotation_smoothing_speed** = ``5.0`` +:ref:`float` **rotation_smoothing_speed** = ``5.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -658,14 +677,14 @@ The angular, asymptotic speed of the camera's rotation smoothing effect when :re .. rst-class:: classref-property -:ref:`Vector2` **zoom** = ``Vector2(1, 1)`` +:ref:`Vector2` **zoom** = ``Vector2(1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_zoom**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_zoom**\ (\ ) -The camera's zoom. A zoom of ``Vector(2, 2)`` doubles the size seen in the viewport. A zoom of ``Vector(0.5, 0.5)`` halves the size seen in the viewport. +The camera's zoom. Higher values are more zoomed in. For example, a zoom of ``Vector2(2.0, 2.0)`` will be twice as zoomed in on each axis (the view covers an area four times smaller). In contrast, a zoom of ``Vector2(0.5, 0.5)`` will be twice as zoomed out on each axis (the view covers an area four times larger). The X and Y components should generally always be set to the same value, unless you wish to stretch the camera view. \ **Note:** :ref:`FontFile.oversampling` does *not* take **Camera2D** zoom into account. This means that zooming in/out will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated unless the font is part of a :ref:`CanvasLayer` that makes it ignore camera zoom. To ensure text remains crisp regardless of zoom, you can enable MSDF font rendering by enabling :ref:`ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field` (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, :ref:`SystemFont.multichannel_signed_distance_field` can be enabled in the inspector. @@ -682,7 +701,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **align**\ (\ ) +|void| **align**\ (\ ) :ref:`🔗` Aligns the camera to the tracked node. @@ -694,7 +713,7 @@ Aligns the camera to the tracked node. .. rst-class:: classref-method -|void| **force_update_scroll**\ (\ ) +|void| **force_update_scroll**\ (\ ) :ref:`🔗` Forces the camera to update scroll immediately. @@ -706,7 +725,7 @@ Forces the camera to update scroll immediately. .. rst-class:: classref-method -:ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| +:ref:`float` **get_drag_margin**\ (\ margin\: :ref:`Side`\ ) |const| :ref:`🔗` Returns the specified :ref:`Side`'s margin. See also :ref:`drag_bottom_margin`, :ref:`drag_top_margin`, :ref:`drag_left_margin`, and :ref:`drag_right_margin`. @@ -718,7 +737,7 @@ Returns the specified :ref:`Side`'s margin. See also :re .. rst-class:: classref-method -:ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| +:ref:`int` **get_limit**\ (\ margin\: :ref:`Side`\ ) |const| :ref:`🔗` Returns the camera limit for the specified :ref:`Side`. See also :ref:`limit_bottom`, :ref:`limit_top`, :ref:`limit_left`, and :ref:`limit_right`. @@ -730,11 +749,25 @@ Returns the camera limit for the specified :ref:`Side`. .. rst-class:: classref-method -:ref:`Vector2` **get_screen_center_position**\ (\ ) |const| +:ref:`Vector2` **get_screen_center_position**\ (\ ) |const| :ref:`🔗` Returns the center of the screen from this camera's point of view, in global coordinates. -\ **Note:** The exact targeted position of the camera may be different. See :ref:`get_target_position`. +\ **Note:** The exact targeted position of the camera may be different. See :ref:`get_target_position()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Camera2D_method_get_screen_rotation: + +.. rst-class:: classref-method + +:ref:`float` **get_screen_rotation**\ (\ ) |const| :ref:`🔗` + +Returns the current screen rotation from this camera's point of view. + +\ **Note:** The screen rotation can be different from :ref:`Node2D.global_rotation` if the camera is rotating smoothly due to :ref:`rotation_smoothing_enabled`. .. rst-class:: classref-item-separator @@ -744,11 +777,11 @@ Returns the center of the screen from this camera's point of view, in global coo .. rst-class:: classref-method -:ref:`Vector2` **get_target_position**\ (\ ) |const| +:ref:`Vector2` **get_target_position**\ (\ ) |const| :ref:`🔗` Returns this camera's target position, in global coordinates. -\ **Note:** The returned value is not the same as :ref:`Node2D.global_position`, as it is affected by the drag properties. It is also not the same as the current position if :ref:`position_smoothing_enabled` is ``true`` (see :ref:`get_screen_center_position`). +\ **Note:** The returned value is not the same as :ref:`Node2D.global_position`, as it is affected by the drag properties. It is also not the same as the current position if :ref:`position_smoothing_enabled` is ``true`` (see :ref:`get_screen_center_position()`). .. rst-class:: classref-item-separator @@ -758,9 +791,9 @@ Returns this camera's target position, in global coordinates. .. rst-class:: classref-method -:ref:`bool` **is_current**\ (\ ) |const| +:ref:`bool` **is_current**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if this **Camera2D** is the active camera (see :ref:`Viewport.get_camera_2d`). +Returns ``true`` if this **Camera2D** is the active camera (see :ref:`Viewport.get_camera_2d()`). .. rst-class:: classref-item-separator @@ -770,7 +803,7 @@ Returns ``true`` if this **Camera2D** is the active camera (see :ref:`Viewport.g .. rst-class:: classref-method -|void| **make_current**\ (\ ) +|void| **make_current**\ (\ ) :ref:`🔗` Forces this **Camera2D** to become the current active one. :ref:`enabled` must be ``true``. @@ -782,7 +815,7 @@ Forces this **Camera2D** to become the current active one. :ref:`enabled` Sets the camera's position immediately to its current smoothing destination. @@ -796,7 +829,7 @@ This method has no effect if :ref:`position_smoothing_enabled`, drag_margin\: :ref:`float`\ ) +|void| **set_drag_margin**\ (\ margin\: :ref:`Side`, drag_margin\: :ref:`float`\ ) :ref:`🔗` Sets the specified :ref:`Side`'s margin. See also :ref:`drag_bottom_margin`, :ref:`drag_top_margin`, :ref:`drag_left_margin`, and :ref:`drag_right_margin`. @@ -808,11 +841,12 @@ Sets the specified :ref:`Side`'s margin. See also :ref:` .. rst-class:: classref-method -|void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) +|void| **set_limit**\ (\ margin\: :ref:`Side`, limit\: :ref:`int`\ ) :ref:`🔗` Sets the camera limit for the specified :ref:`Side`. See also :ref:`limit_bottom`, :ref:`limit_top`, :ref:`limit_left`, and :ref:`limit_right`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_camera3d.rst b/classes/class_camera3d.rst index 9020c383286..a29482fd75b 100644 --- a/classes/class_camera3d.rst +++ b/classes/class_camera3d.rst @@ -28,7 +28,7 @@ Description Tutorials --------- -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -131,7 +131,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **ProjectionType**: +enum **ProjectionType**: :ref:`🔗` .. _class_Camera3D_constant_PROJECTION_PERSPECTIVE: @@ -165,7 +165,7 @@ Frustum projection. This mode allows adjusting :ref:`frustum_offset` .. _class_Camera3D_constant_KEEP_WIDTH: @@ -191,7 +191,7 @@ Preserves the vertical aspect ratio; also known as Hor+ scaling. This is usually .. rst-class:: classref-enumeration -enum **DopplerTracking**: +enum **DopplerTracking**: :ref:`🔗` .. _class_Camera3D_constant_DOPPLER_TRACKING_DISABLED: @@ -230,7 +230,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`CameraAttributes` **attributes** +:ref:`CameraAttributes` **attributes** :ref:`🔗` .. rst-class:: classref-property-setget @@ -247,7 +247,7 @@ The :ref:`CameraAttributes` to use for this camera. .. rst-class:: classref-property -:ref:`Compositor` **compositor** +:ref:`Compositor` **compositor** :ref:`🔗` .. rst-class:: classref-property-setget @@ -264,7 +264,7 @@ The :ref:`Compositor` to use for this camera. .. rst-class:: classref-property -:ref:`int` **cull_mask** = ``1048575`` +:ref:`int` **cull_mask** = ``1048575`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -275,7 +275,7 @@ The culling mask that describes which :ref:`VisualInstance3D.layers` 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`. +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. @@ -287,7 +287,7 @@ To adjust :ref:`cull_mask` more easily using .. rst-class:: classref-property -:ref:`bool` **current** = ``false`` +:ref:`bool` **current** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -306,14 +306,16 @@ If multiple cameras are in the scene, one will always be made current. For examp .. rst-class:: classref-property -:ref:`DopplerTracking` **doppler_tracking** = ``0`` +:ref:`DopplerTracking` **doppler_tracking** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_doppler_tracking**\ (\ value\: :ref:`DopplerTracking`\ ) - :ref:`DopplerTracking` **get_doppler_tracking**\ (\ ) -If not :ref:`DOPPLER_TRACKING_DISABLED`, this camera will simulate the `Doppler effect `__ for objects changed in particular ``_process`` methods. See :ref:`DopplerTracking` for possible values. +If not :ref:`DOPPLER_TRACKING_DISABLED`, this camera will simulate the `Doppler effect `__ for objects changed in particular ``_process`` methods. + +\ **Note:** The Doppler effect will only be heard on :ref:`AudioStreamPlayer3D`\ s if :ref:`AudioStreamPlayer3D.doppler_tracking` is not set to :ref:`AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED`. .. rst-class:: classref-item-separator @@ -323,7 +325,7 @@ If not :ref:`DOPPLER_TRACKING_DISABLED` **environment** +:ref:`Environment` **environment** :ref:`🔗` .. rst-class:: classref-property-setget @@ -340,7 +342,7 @@ The :ref:`Environment` to use for this camera. .. rst-class:: classref-property -:ref:`float` **far** = ``4000.0`` +:ref:`float` **far** = ``4000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -357,7 +359,7 @@ The distance to the far culling boundary for this camera relative to its local Z .. rst-class:: classref-property -:ref:`float` **fov** = ``75.0`` +:ref:`float` **fov** = ``75.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -384,7 +386,7 @@ For reference, the default vertical field of view value (``75.0``) is equivalent .. rst-class:: classref-property -:ref:`Vector2` **frustum_offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **frustum_offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -403,7 +405,7 @@ The camera's frustum offset. This can be changed from the default to create "til .. rst-class:: classref-property -:ref:`float` **h_offset** = ``0.0`` +:ref:`float` **h_offset** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -420,7 +422,7 @@ The horizontal (X) offset of the camera viewport. .. rst-class:: classref-property -:ref:`KeepAspect` **keep_aspect** = ``1`` +:ref:`KeepAspect` **keep_aspect** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -437,7 +439,7 @@ The axis to lock during :ref:`fov`/:ref:`size` **near** = ``0.05`` +:ref:`float` **near** = ``0.05`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -454,7 +456,7 @@ The distance to the near culling boundary for this camera relative to its local .. rst-class:: classref-property -:ref:`ProjectionType` **projection** = ``0`` +:ref:`ProjectionType` **projection** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -471,7 +473,7 @@ The camera's projection mode. In :ref:`PROJECTION_PERSPECTIVE` **size** = ``1.0`` +:ref:`float` **size** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -488,7 +490,7 @@ The camera's size in meters measured as the diameter of the width or height, dep .. rst-class:: classref-property -:ref:`float` **v_offset** = ``0.0`` +:ref:`float` **v_offset** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -510,7 +512,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **clear_current**\ (\ enable_next\: :ref:`bool` = true\ ) +|void| **clear_current**\ (\ enable_next\: :ref:`bool` = true\ ) :ref:`🔗` If this is the current camera, remove it from being current. If ``enable_next`` is ``true``, request to make the next camera current, if any. @@ -522,7 +524,7 @@ If this is the current camera, remove it from being current. If ``enable_next`` .. rst-class:: classref-method -:ref:`Projection` **get_camera_projection**\ (\ ) |const| +:ref:`Projection` **get_camera_projection**\ (\ ) |const| :ref:`🔗` Returns the projection matrix that this camera uses to render to its associated viewport. The camera must be part of the scene tree to function. @@ -534,7 +536,7 @@ Returns the projection matrix that this camera uses to render to its associated .. rst-class:: classref-method -:ref:`RID` **get_camera_rid**\ (\ ) |const| +:ref:`RID` **get_camera_rid**\ (\ ) |const| :ref:`🔗` Returns the camera's RID from the :ref:`RenderingServer`. @@ -546,7 +548,7 @@ Returns the camera's RID from the :ref:`RenderingServer`. .. rst-class:: classref-method -:ref:`Transform3D` **get_camera_transform**\ (\ ) |const| +:ref:`Transform3D` **get_camera_transform**\ (\ ) |const| :ref:`🔗` Returns the transform of the camera plus the vertical (:ref:`v_offset`) and horizontal (:ref:`h_offset`) offsets; and any other adjustments made to the position and orientation of the camera by subclassed cameras such as :ref:`XRCamera3D`. @@ -558,7 +560,7 @@ Returns the transform of the camera plus the vertical (:ref:`v_offset` **get_cull_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| +:ref:`bool` **get_cull_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether or not the specified layer of the :ref:`cull_mask` is enabled, given a ``layer_number`` between 1 and 20. @@ -570,7 +572,7 @@ Returns whether or not the specified layer of the :ref:`cull_mask`\[:ref:`Plane`\] **get_frustum**\ (\ ) |const| +:ref:`Array`\[:ref:`Plane`\] **get_frustum**\ (\ ) |const| :ref:`🔗` Returns the camera's frustum planes in world space units as an array of :ref:`Plane`\ s in the following order: near, far, left, top, right, bottom. Not to be confused with :ref:`frustum_offset`. @@ -582,7 +584,7 @@ Returns the camera's frustum planes in world space units as an array of :ref:`Pl .. rst-class:: classref-method -:ref:`RID` **get_pyramid_shape_rid**\ (\ ) +:ref:`RID` **get_pyramid_shape_rid**\ (\ ) :ref:`🔗` Returns the RID of a pyramid shape encompassing the camera's view frustum, ignoring the camera's near plane. The tip of the pyramid represents the position of the camera. @@ -594,7 +596,7 @@ Returns the RID of a pyramid shape encompassing the camera's view frustum, ignor .. rst-class:: classref-method -:ref:`bool` **is_position_behind**\ (\ world_point\: :ref:`Vector3`\ ) |const| +:ref:`bool` **is_position_behind**\ (\ world_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns ``true`` if the given position is behind the camera (the blue part of the linked diagram). `See this diagram `__ for an overview of position query methods. @@ -608,7 +610,7 @@ Returns ``true`` if the given position is behind the camera (the blue part of th .. rst-class:: classref-method -:ref:`bool` **is_position_in_frustum**\ (\ world_point\: :ref:`Vector3`\ ) |const| +:ref:`bool` **is_position_in_frustum**\ (\ world_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns ``true`` if the given position is inside the camera's frustum (the green part of the linked diagram). `See this diagram `__ for an overview of position query methods. @@ -620,7 +622,7 @@ Returns ``true`` if the given position is inside the camera's frustum (the green .. rst-class:: classref-method -|void| **make_current**\ (\ ) +|void| **make_current**\ (\ ) :ref:`🔗` Makes this camera the current camera for the :ref:`Viewport` (see class description). If the camera node is outside the scene tree, it will attempt to become current once it's added. @@ -632,7 +634,7 @@ Makes this camera the current camera for the :ref:`Viewport` (se .. rst-class:: classref-method -:ref:`Vector3` **project_local_ray_normal**\ (\ screen_point\: :ref:`Vector2`\ ) |const| +:ref:`Vector3` **project_local_ray_normal**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` Returns a normal vector from the screen point location directed along the camera. Orthogonal cameras are normalized. Perspective cameras account for perspective, screen width/height, etc. @@ -644,7 +646,7 @@ Returns a normal vector from the screen point location directed along the camera .. rst-class:: classref-method -:ref:`Vector3` **project_position**\ (\ screen_point\: :ref:`Vector2`, z_depth\: :ref:`float`\ ) |const| +:ref:`Vector3` **project_position**\ (\ screen_point\: :ref:`Vector2`, z_depth\: :ref:`float`\ ) |const| :ref:`🔗` Returns the 3D point in world space that maps to the given 2D coordinate in the :ref:`Viewport` rectangle on a plane that is the given ``z_depth`` distance into the scene away from the camera. @@ -656,7 +658,7 @@ Returns the 3D point in world space that maps to the given 2D coordinate in the .. rst-class:: classref-method -:ref:`Vector3` **project_ray_normal**\ (\ screen_point\: :ref:`Vector2`\ ) |const| +:ref:`Vector3` **project_ray_normal**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` Returns a normal vector in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. @@ -668,7 +670,7 @@ Returns a normal vector in world space, that is the result of projecting a point .. rst-class:: classref-method -:ref:`Vector3` **project_ray_origin**\ (\ screen_point\: :ref:`Vector2`\ ) |const| +:ref:`Vector3` **project_ray_origin**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` Returns a 3D position in world space, that is the result of projecting a point on the :ref:`Viewport` rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. @@ -680,7 +682,7 @@ Returns a 3D position in world space, that is the result of projecting a point o .. rst-class:: classref-method -|void| **set_cull_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) +|void| **set_cull_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` Based on ``value``, enables or disables the specified layer in the :ref:`cull_mask`, given a ``layer_number`` between 1 and 20. @@ -692,7 +694,7 @@ Based on ``value``, enables or disables the specified layer in the :ref:`cull_ma .. rst-class:: classref-method -|void| **set_frustum**\ (\ size\: :ref:`float`, offset\: :ref:`Vector2`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) +|void| **set_frustum**\ (\ size\: :ref:`float`, offset\: :ref:`Vector2`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) :ref:`🔗` Sets the camera projection to frustum mode (see :ref:`PROJECTION_FRUSTUM`), by specifying a ``size``, an ``offset``, and the ``z_near`` and ``z_far`` clip planes in world space units. See also :ref:`frustum_offset`. @@ -704,9 +706,11 @@ Sets the camera projection to frustum mode (see :ref:`PROJECTION_FRUSTUM`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) +|void| **set_orthogonal**\ (\ size\: :ref:`float`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) :ref:`🔗` + +Sets the camera projection to orthogonal mode (see :ref:`PROJECTION_ORTHOGONAL`), by specifying a ``size``, and the ``z_near`` and ``z_far`` clip planes in world space units. -Sets the camera projection to orthogonal mode (see :ref:`PROJECTION_ORTHOGONAL`), by specifying a ``size``, and the ``z_near`` and ``z_far`` clip planes in world space units. (As a hint, 2D games often use this projection, with values specified in pixels.) +As a hint, 3D games that look 2D often use this projection, with ``size`` specified in pixels. .. rst-class:: classref-item-separator @@ -716,7 +720,7 @@ Sets the camera projection to orthogonal mode (see :ref:`PROJECTION_ORTHOGONAL`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) +|void| **set_perspective**\ (\ fov\: :ref:`float`, z_near\: :ref:`float`, z_far\: :ref:`float`\ ) :ref:`🔗` Sets the camera projection to perspective mode (see :ref:`PROJECTION_PERSPECTIVE`), by specifying a ``fov`` (field of view) angle in degrees, and the ``z_near`` and ``z_far`` clip planes in world space units. @@ -728,11 +732,11 @@ Sets the camera projection to perspective mode (see :ref:`PROJECTION_PERSPECTIVE .. rst-class:: classref-method -:ref:`Vector2` **unproject_position**\ (\ world_point\: :ref:`Vector3`\ ) |const| +:ref:`Vector2` **unproject_position**\ (\ world_point\: :ref:`Vector3`\ ) |const| :ref:`🔗` Returns the 2D coordinate in the :ref:`Viewport` rectangle that maps to the given 3D point in world space. -\ **Note:** When using this to position GUI elements over a 3D viewport, use :ref:`is_position_behind` to prevent them from appearing if the 3D point is behind the camera: +\ **Note:** When using this to position GUI elements over a 3D viewport, use :ref:`is_position_behind()` to prevent them from appearing if the 3D point is behind the camera: :: @@ -742,6 +746,7 @@ Returns the 2D coordinate in the :ref:`Viewport` rectangle that control.position = get_viewport().get_camera_3d().unproject_position(global_transform.origin) .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_cameraattributes.rst b/classes/class_cameraattributes.rst index 3104407d7d2..09f3c6dbf60 100644 --- a/classes/class_cameraattributes.rst +++ b/classes/class_cameraattributes.rst @@ -62,7 +62,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **auto_exposure_enabled** = ``false`` +:ref:`bool` **auto_exposure_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -79,7 +79,7 @@ If ``true``, enables the tonemapping auto exposure mode of the scene renderer. I .. rst-class:: classref-property -:ref:`float` **auto_exposure_scale** = ``0.4`` +:ref:`float` **auto_exposure_scale** = ``0.4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -96,7 +96,7 @@ The scale of the auto exposure effect. Affects the intensity of auto exposure. .. rst-class:: classref-property -:ref:`float` **auto_exposure_speed** = ``0.5`` +:ref:`float` **auto_exposure_speed** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -113,7 +113,7 @@ The speed of the auto exposure effect. Affects the time needed for the camera to .. rst-class:: classref-property -:ref:`float` **exposure_multiplier** = ``1.0`` +:ref:`float` **exposure_multiplier** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -130,16 +130,21 @@ Multiplier for the exposure amount. A higher value results in a brighter image. .. rst-class:: classref-property -:ref:`float` **exposure_sensitivity** = ``100.0`` +:ref:`float` **exposure_sensitivity** = ``100.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_exposure_sensitivity**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_exposure_sensitivity**\ (\ ) -Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. When :ref:`auto_exposure_enabled` this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. +Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. + +If :ref:`auto_exposure_enabled` is ``true``, this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + +\ **Note:** Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_cameraattributesphysical.rst b/classes/class_cameraattributesphysical.rst index 3b3c1760fcf..9aee1d44a48 100644 --- a/classes/class_cameraattributesphysical.rst +++ b/classes/class_cameraattributesphysical.rst @@ -85,7 +85,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **auto_exposure_max_exposure_value** = ``10.0`` +:ref:`float` **auto_exposure_max_exposure_value** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -102,14 +102,14 @@ The maximum luminance (in EV100) used when calculating auto exposure. When calcu .. rst-class:: classref-property -:ref:`float` **auto_exposure_min_exposure_value** = ``-8.0`` +:ref:`float` **auto_exposure_min_exposure_value** = ``-8.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_exposure_min_exposure_value**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_auto_exposure_min_exposure_value**\ (\ ) -The minimum luminance luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. +The minimum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. .. rst-class:: classref-item-separator @@ -119,7 +119,7 @@ The minimum luminance luminance (in EV100) used when calculating auto exposure. .. rst-class:: classref-property -:ref:`float` **exposure_aperture** = ``16.0`` +:ref:`float` **exposure_aperture** = ``16.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -138,7 +138,7 @@ Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physi .. rst-class:: classref-property -:ref:`float` **exposure_shutter_speed** = ``100.0`` +:ref:`float` **exposure_shutter_speed** = ``100.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -157,7 +157,7 @@ Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physi .. rst-class:: classref-property -:ref:`float` **frustum_far** = ``4000.0`` +:ref:`float` **frustum_far** = ``4000.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -174,7 +174,7 @@ Override value for :ref:`Camera3D.far`. Used intern .. rst-class:: classref-property -:ref:`float` **frustum_focal_length** = ``35.0`` +:ref:`float` **frustum_focal_length** = ``35.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -191,7 +191,7 @@ Distance between camera lens and camera aperture, measured in millimeters. Contr .. rst-class:: classref-property -:ref:`float` **frustum_focus_distance** = ``10.0`` +:ref:`float` **frustum_focus_distance** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -208,7 +208,7 @@ Distance from camera of object that will be in focus, measured in meters. Intern .. rst-class:: classref-property -:ref:`float` **frustum_near** = ``0.05`` +:ref:`float` **frustum_near** = ``0.05`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -230,11 +230,12 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_fov**\ (\ ) |const| +:ref:`float` **get_fov**\ (\ ) |const| :ref:`🔗` Returns the vertical field of view that corresponds to the :ref:`frustum_focal_length`. This value is calculated internally whenever :ref:`frustum_focal_length` is changed. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_cameraattributespractical.rst b/classes/class_cameraattributespractical.rst index 25a6d7bb593..35344520904 100644 --- a/classes/class_cameraattributespractical.rst +++ b/classes/class_cameraattributespractical.rst @@ -64,7 +64,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **auto_exposure_max_sensitivity** = ``800.0`` +:ref:`float` **auto_exposure_max_sensitivity** = ``800.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -81,7 +81,7 @@ The maximum sensitivity (in ISO) used when calculating auto exposure. When calcu .. rst-class:: classref-property -:ref:`float` **auto_exposure_min_sensitivity** = ``0.0`` +:ref:`float` **auto_exposure_min_sensitivity** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -98,7 +98,7 @@ The minimum sensitivity (in ISO) used when calculating auto exposure. When calcu .. rst-class:: classref-property -:ref:`float` **dof_blur_amount** = ``0.1`` +:ref:`float` **dof_blur_amount** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -115,7 +115,7 @@ Sets the maximum amount of blur. When using physically-based blur amounts, will .. rst-class:: classref-property -:ref:`float` **dof_blur_far_distance** = ``10.0`` +:ref:`float` **dof_blur_far_distance** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -132,7 +132,7 @@ Objects further from the :ref:`Camera3D` by this amount will be .. rst-class:: classref-property -:ref:`bool` **dof_blur_far_enabled** = ``false`` +:ref:`bool` **dof_blur_far_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -151,7 +151,7 @@ Enables depth of field blur for objects further than :ref:`dof_blur_far_distance .. rst-class:: classref-property -:ref:`float` **dof_blur_far_transition** = ``5.0`` +:ref:`float` **dof_blur_far_transition** = ``5.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -168,7 +168,7 @@ When positive, distance over which (starting from :ref:`dof_blur_far_distance` **dof_blur_near_distance** = ``2.0`` +:ref:`float` **dof_blur_near_distance** = ``2.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -185,7 +185,7 @@ Objects closer from the :ref:`Camera3D` by this amount will be b .. rst-class:: classref-property -:ref:`bool` **dof_blur_near_enabled** = ``false`` +:ref:`bool` **dof_blur_near_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -204,7 +204,7 @@ Enables depth of field blur for objects closer than :ref:`dof_blur_near_distance .. rst-class:: classref-property -:ref:`float` **dof_blur_near_transition** = ``1.0`` +:ref:`float` **dof_blur_near_transition** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -214,6 +214,7 @@ Enables depth of field blur for objects closer than :ref:`dof_blur_near_distance When positive, distance over which blur effect will scale from 0 to :ref:`dof_blur_amount`, ending at :ref:`dof_blur_near_distance`. When negative, uses physically-based scaling so depth of field effect will scale from 0 at :ref:`dof_blur_near_distance` and will increase in a physically accurate way as objects get closer to the :ref:`Camera3D`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_camerafeed.rst b/classes/class_camerafeed.rst index 39512f121db..f77a069360b 100644 --- a/classes/class_camerafeed.rst +++ b/classes/class_camerafeed.rst @@ -23,6 +23,8 @@ A camera feed gives you access to a single physical camera attached to your devi \ **Note:** Many cameras will return YCbCr images which are split into two textures and need to be combined in a shader. Godot does this automatically for you if you set the environment to show the camera image in the background. +\ **Note:** This class is currently only implemented on Linux, Android, macOS, and iOS. On other platforms no **CameraFeed**\ s will be available. To get a **CameraFeed** on iOS, the camera plugin from `godot-ios-plugins `__ is required. + .. rst-class:: classref-reftable-group Properties @@ -36,6 +38,8 @@ Properties +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ | :ref:`Transform2D` | :ref:`feed_transform` | ``Transform2D(1, 0, 0, -1, 0, 1)`` | +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ + | :ref:`Array` | :ref:`formats` | ``[]`` | + +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ .. rst-class:: classref-reftable-group @@ -45,15 +49,62 @@ Methods .. table:: :widths: auto - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`FeedDataType` | :ref:`get_datatype`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_id`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`String` | :ref:`get_name`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`FeedPosition` | :ref:`get_position`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`_activate_feed`\ (\ ) |virtual| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_deactivate_feed`\ (\ ) |virtual| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FeedDataType` | :ref:`get_datatype`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_id`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_name`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FeedPosition` | :ref:`get_position`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_texture_tex_id`\ (\ feed_image_type\: :ref:`FeedImage`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_external`\ (\ width\: :ref:`int`, height\: :ref:`int`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`set_format`\ (\ index\: :ref:`int`, parameters\: :ref:`Dictionary`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_name`\ (\ name\: :ref:`String`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_position`\ (\ position\: :ref:`FeedPosition`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_rgb_image`\ (\ rgb_image\: :ref:`Image`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_ycbcr_image`\ (\ ycbcr_image\: :ref:`Image`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_CameraFeed_signal_format_changed: + +.. rst-class:: classref-signal + +**format_changed**\ (\ ) :ref:`🔗` + +Emitted when the format has changed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_signal_frame_changed: + +.. rst-class:: classref-signal + +**frame_changed**\ (\ ) :ref:`🔗` + +Emitted when a new frame is available. .. rst-class:: classref-section-separator @@ -68,7 +119,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FeedDataType**: +enum **FeedDataType**: :ref:`🔗` .. _class_CameraFeed_constant_FEED_NOIMAGE: @@ -102,6 +153,14 @@ Feed supplies YCbCr images that need to be converted to RGB. Feed supplies separate Y and CbCr images that need to be combined and converted to RGB. +.. _class_CameraFeed_constant_FEED_EXTERNAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_EXTERNAL** = ``4`` + +Feed supplies external image. + .. rst-class:: classref-item-separator ---- @@ -110,7 +169,7 @@ Feed supplies separate Y and CbCr images that need to be combined and converted .. rst-class:: classref-enumeration -enum **FeedPosition**: +enum **FeedPosition**: :ref:`🔗` .. _class_CameraFeed_constant_FEED_UNSPECIFIED: @@ -149,7 +208,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **feed_is_active** = ``false`` +:ref:`bool` **feed_is_active** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -166,7 +225,7 @@ If ``true``, the feed is active. .. rst-class:: classref-property -:ref:`Transform2D` **feed_transform** = ``Transform2D(1, 0, 0, -1, 0, 1)`` +:ref:`Transform2D` **feed_transform** = ``Transform2D(1, 0, 0, -1, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -175,6 +234,22 @@ If ``true``, the feed is active. The transform applied to the camera's image. +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_property_formats: + +.. rst-class:: classref-property + +:ref:`Array` **formats** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- :ref:`Array` **get_formats**\ (\ ) + +Formats supported by the feed. Each entry is a :ref:`Dictionary` describing format parameters. + .. rst-class:: classref-section-separator ---- @@ -184,11 +259,35 @@ The transform applied to the camera's image. Method Descriptions ------------------- +.. _class_CameraFeed_private_method__activate_feed: + +.. rst-class:: classref-method + +:ref:`bool` **_activate_feed**\ (\ ) |virtual| :ref:`🔗` + +Called when the camera feed is activated. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_private_method__deactivate_feed: + +.. rst-class:: classref-method + +|void| **_deactivate_feed**\ (\ ) |virtual| :ref:`🔗` + +Called when the camera feed is deactivated. + +.. rst-class:: classref-item-separator + +---- + .. _class_CameraFeed_method_get_datatype: .. rst-class:: classref-method -:ref:`FeedDataType` **get_datatype**\ (\ ) |const| +:ref:`FeedDataType` **get_datatype**\ (\ ) |const| :ref:`🔗` Returns feed image data type. @@ -200,7 +299,7 @@ Returns feed image data type. .. rst-class:: classref-method -:ref:`int` **get_id**\ (\ ) |const| +:ref:`int` **get_id**\ (\ ) |const| :ref:`🔗` Returns the unique ID for this feed. @@ -212,7 +311,7 @@ Returns the unique ID for this feed. .. rst-class:: classref-method -:ref:`String` **get_name**\ (\ ) |const| +:ref:`String` **get_name**\ (\ ) |const| :ref:`🔗` Returns the camera's name. @@ -224,11 +323,102 @@ Returns the camera's name. .. rst-class:: classref-method -:ref:`FeedPosition` **get_position**\ (\ ) |const| +:ref:`FeedPosition` **get_position**\ (\ ) |const| :ref:`🔗` Returns the position of camera on the device. +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_texture_tex_id: + +.. rst-class:: classref-method + +:ref:`int` **get_texture_tex_id**\ (\ feed_image_type\: :ref:`FeedImage`\ ) :ref:`🔗` + +Returns the texture backend ID (usable by some external libraries that need a handle to a texture to write data). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_external: + +.. rst-class:: classref-method + +|void| **set_external**\ (\ width\: :ref:`int`, height\: :ref:`int`\ ) :ref:`🔗` + +Sets the feed as external feed provided by another library. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_format: + +.. rst-class:: classref-method + +:ref:`bool` **set_format**\ (\ index\: :ref:`int`, parameters\: :ref:`Dictionary`\ ) :ref:`🔗` + +Sets the feed format parameters for the given ``index`` in the :ref:`formats` array. Returns ``true`` on success. By default, the YUYV encoded stream is transformed to :ref:`FEED_RGB`. The YUYV encoded stream output format can be changed by setting ``parameters``'s ``output`` entry to one of the following: + +- ``"separate"`` will result in :ref:`FEED_YCBCR_SEP`; + +- ``"grayscale"`` will result in desaturated :ref:`FEED_RGB`; + +- ``"copy"`` will result in :ref:`FEED_YCBCR`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_name: + +.. rst-class:: classref-method + +|void| **set_name**\ (\ name\: :ref:`String`\ ) :ref:`🔗` + +Sets the camera's name. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_position: + +.. rst-class:: classref-method + +|void| **set_position**\ (\ position\: :ref:`FeedPosition`\ ) :ref:`🔗` + +Sets the position of this camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_rgb_image: + +.. rst-class:: classref-method + +|void| **set_rgb_image**\ (\ rgb_image\: :ref:`Image`\ ) :ref:`🔗` + +Sets RGB image for this feed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_ycbcr_image: + +.. rst-class:: classref-method + +|void| **set_ycbcr_image**\ (\ ycbcr_image\: :ref:`Image`\ ) :ref:`🔗` + +Sets YCbCr image for this feed. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_cameraserver.rst b/classes/class_cameraserver.rst index dca7797eda0..8172be2d4e7 100644 --- a/classes/class_cameraserver.rst +++ b/classes/class_cameraserver.rst @@ -23,7 +23,19 @@ The **CameraServer** keeps track of different cameras accessible in Godot. These It is notably used to provide AR modules with a video feed from the camera. -\ **Note:** This class is currently only implemented on macOS and iOS. On other platforms, no :ref:`CameraFeed`\ s will be available. +\ **Note:** This class is currently only implemented on Linux, Android, macOS, and iOS. On other platforms no :ref:`CameraFeed`\ s will be available. To get a :ref:`CameraFeed` on iOS, the camera plugin from `godot-ios-plugins `__ is required. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+-----------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`monitoring_feeds` | ``false`` | + +-------------------------+-----------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group @@ -58,7 +70,7 @@ Signals .. rst-class:: classref-signal -**camera_feed_added**\ (\ id\: :ref:`int`\ ) +**camera_feed_added**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`CameraFeed` is added (e.g. a webcam is plugged in). @@ -70,10 +82,22 @@ Emitted when a :ref:`CameraFeed` is added (e.g. a webcam is pl .. rst-class:: classref-signal -**camera_feed_removed**\ (\ id\: :ref:`int`\ ) +**camera_feed_removed**\ (\ id\: :ref:`int`\ ) :ref:`🔗` Emitted when a :ref:`CameraFeed` is removed (e.g. a webcam is unplugged). +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraServer_signal_camera_feeds_updated: + +.. rst-class:: classref-signal + +**camera_feeds_updated**\ (\ ) :ref:`🔗` + +Emitted when camera feeds are updated. + .. rst-class:: classref-section-separator ---- @@ -87,7 +111,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FeedImage**: +enum **FeedImage**: :ref:`🔗` .. _class_CameraServer_constant_FEED_RGBA_IMAGE: @@ -121,6 +145,59 @@ The Y component camera image. The CbCr component camera image. +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_CameraServer_property_monitoring_feeds: + +.. rst-class:: classref-property + +:ref:`bool` **monitoring_feeds** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_monitoring_feeds**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_monitoring_feeds**\ (\ ) + +If ``true``, the server is actively monitoring available camera feeds. + +This has a performance cost, so only set it to ``true`` when you're actively accessing the camera. + +\ **Note:** After setting it to ``true``, you can receive updated camera feeds through the :ref:`camera_feeds_updated` signal. + + +.. tabs:: + + .. code-tab:: gdscript + + func _ready(): + CameraServer.camera_feeds_updated.connect(_on_camera_feeds_updated) + CameraServer.monitoring_feeds = true + + func _on_camera_feeds_updated(): + var feeds = CameraServer.feeds() + + .. code-tab:: csharp + + public override void _Ready() + { + CameraServer.CameraFeedsUpdated += OnCameraFeedsUpdated; + CameraServer.MonitoringFeeds = true; + } + + void OnCameraFeedsUpdated() + { + var feeds = CameraServer.Feeds(); + } + + + .. rst-class:: classref-section-separator ---- @@ -134,7 +211,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_feed**\ (\ feed\: :ref:`CameraFeed`\ ) +|void| **add_feed**\ (\ feed\: :ref:`CameraFeed`\ ) :ref:`🔗` Adds the camera ``feed`` to the camera server. @@ -146,7 +223,7 @@ Adds the camera ``feed`` to the camera server. .. rst-class:: classref-method -:ref:`Array`\[:ref:`CameraFeed`\] **feeds**\ (\ ) +:ref:`Array`\[:ref:`CameraFeed`\] **feeds**\ (\ ) :ref:`🔗` Returns an array of :ref:`CameraFeed`\ s. @@ -158,7 +235,7 @@ Returns an array of :ref:`CameraFeed`\ s. .. rst-class:: classref-method -:ref:`CameraFeed` **get_feed**\ (\ index\: :ref:`int`\ ) +:ref:`CameraFeed` **get_feed**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Returns the :ref:`CameraFeed` corresponding to the camera with the given ``index``. @@ -170,7 +247,7 @@ Returns the :ref:`CameraFeed` corresponding to the camera with .. rst-class:: classref-method -:ref:`int` **get_feed_count**\ (\ ) +:ref:`int` **get_feed_count**\ (\ ) :ref:`🔗` Returns the number of :ref:`CameraFeed`\ s registered. @@ -182,11 +259,12 @@ Returns the number of :ref:`CameraFeed`\ s registered. .. rst-class:: classref-method -|void| **remove_feed**\ (\ feed\: :ref:`CameraFeed`\ ) +|void| **remove_feed**\ (\ feed\: :ref:`CameraFeed`\ ) :ref:`🔗` Removes the specified camera ``feed``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_cameratexture.rst b/classes/class_cameratexture.rst index e0d4f6f5d09..74291b04ce8 100644 --- a/classes/class_cameratexture.rst +++ b/classes/class_cameratexture.rst @@ -54,7 +54,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **camera_feed_id** = ``0`` +:ref:`int` **camera_feed_id** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -71,7 +71,7 @@ The ID of the :ref:`CameraFeed` for which we want to display t .. rst-class:: classref-property -:ref:`bool` **camera_is_active** = ``false`` +:ref:`bool` **camera_is_active** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -88,7 +88,7 @@ Convenience property that gives access to the active property of the :ref:`Camer .. rst-class:: classref-property -:ref:`FeedImage` **which_feed** = ``0`` +:ref:`FeedImage` **which_feed** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -98,6 +98,7 @@ Convenience property that gives access to the active property of the :ref:`Camer Which image within the :ref:`CameraFeed` we want access to, important if the camera image is split in a Y and CbCr component. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_canvasgroup.rst b/classes/class_canvasgroup.rst index ad6c99f447d..950c94569f4 100644 --- a/classes/class_canvasgroup.rst +++ b/classes/class_canvasgroup.rst @@ -27,16 +27,16 @@ Child :ref:`CanvasItem` nodes of a **CanvasGroup** are drawn a shader_type canvas_item; render_mode unshaded; - + uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest; - + void fragment() { vec4 c = textureLod(screen_texture, SCREEN_UV, 0.0); - + if (c.a > 0.0001) { c.rgb /= c.a; } - + COLOR *= c; } @@ -71,7 +71,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **clear_margin** = ``10.0`` +:ref:`float` **clear_margin** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -88,7 +88,7 @@ Sets the size of the margin used to expand the clearing rect of this **CanvasGro .. rst-class:: classref-property -:ref:`float` **fit_margin** = ``10.0`` +:ref:`float` **fit_margin** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -105,7 +105,7 @@ Sets the size of a margin used to expand the drawable rect of this **CanvasGroup .. rst-class:: classref-property -:ref:`bool` **use_mipmaps** = ``false`` +:ref:`bool` **use_mipmaps** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -115,6 +115,7 @@ Sets the size of a margin used to expand the drawable rect of this **CanvasGroup If ``true``, calculates mipmaps for the backbuffer before drawing the **CanvasGroup** so that mipmaps can be used in a custom :ref:`ShaderMaterial` attached to the **CanvasGroup**. Generating mipmaps has a performance cost so this should not be enabled unless required. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index 4b740494bbc..b35717dcce2 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -23,12 +23,14 @@ Description 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 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. +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 on their canvas layer. 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 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. +Note that properties like transform, modulation, and visibility are only propagated to *direct* **CanvasItem** child nodes. If there is a non-**CanvasItem** node in between, like :ref:`Node` or :ref:`AnimationPlayer`, the **CanvasItem** nodes below will have an independent position and :ref:`modulate` chain. See also :ref:`top_level`. + .. rst-class:: classref-introduction-group Tutorials @@ -38,7 +40,7 @@ Tutorials - :doc:`Custom drawing in 2D <../tutorials/2d/custom_drawing_in_2d>` -- `Audio Spectrum Demo `__ +- `Audio Spectrum Visualizer Demo `__ .. rst-class:: classref-reftable-group @@ -88,123 +90,127 @@ Methods .. table:: :widths: auto - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_draw`\ (\ ) |virtual| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_animation_slice`\ (\ animation_length\: :ref:`float`, slice_begin\: :ref:`float`, slice_end\: :ref:`float`, offset\: :ref:`float` = 0.0\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_arc`\ (\ center\: :ref:`Vector2`, radius\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_char`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_char_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, size\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_circle`\ (\ position\: :ref:`Vector2`, radius\: :ref:`float`, color\: :ref:`Color`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_colored_polygon`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_dashed_line`\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, dash\: :ref:`float` = 2.0, aligned\: :ref:`bool` = true\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_end_animation`\ (\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_lcd_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_line`\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_mesh`\ (\ mesh\: :ref:`Mesh`, texture\: :ref:`Texture2D`, transform\: :ref:`Transform2D` = Transform2D(1, 0, 0, 1, 0, 0), modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_msdf_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), outline\: :ref:`float` = 0.0, pixel_range\: :ref:`float` = 4.0, scale\: :ref:`float` = 1.0\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_multiline`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_multiline_colors`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_multiline_string`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_multiline_string_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_multimesh`\ (\ multimesh\: :ref:`MultiMesh`, texture\: :ref:`Texture2D`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_polygon`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_polyline`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_polyline_colors`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_primitive`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array`, texture\: :ref:`Texture2D` = null\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_rect`\ (\ rect\: :ref:`Rect2`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_set_transform`\ (\ position\: :ref:`Vector2`, rotation\: :ref:`float` = 0.0, scale\: :ref:`Vector2` = Vector2(1, 1)\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_set_transform_matrix`\ (\ xform\: :ref:`Transform2D`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_string`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_string_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_style_box`\ (\ style_box\: :ref:`StyleBox`, rect\: :ref:`Rect2`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_texture`\ (\ texture\: :ref:`Texture2D`, position\: :ref:`Vector2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_texture_rect`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, tile\: :ref:`bool`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`draw_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false, clip_uv\: :ref:`bool` = true\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`force_update_transform`\ (\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_canvas`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_canvas_item`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`CanvasLayer` | :ref:`get_canvas_layer_node`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform2D` | :ref:`get_canvas_transform`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`get_global_mouse_position`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform2D` | :ref:`get_global_transform`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform2D` | :ref:`get_global_transform_with_canvas`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`get_local_mouse_position`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform2D` | :ref:`get_screen_transform`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform2D` | :ref:`get_transform`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Rect2` | :ref:`get_viewport_rect`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform2D` | :ref:`get_viewport_transform`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_visibility_layer_bit`\ (\ layer\: :ref:`int`\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`World2D` | :ref:`get_world_2d`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`hide`\ (\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_local_transform_notification_enabled`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_transform_notification_enabled`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_visible_in_tree`\ (\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`make_canvas_position_local`\ (\ screen_point\: :ref:`Vector2`\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`InputEvent` | :ref:`make_input_local`\ (\ event\: :ref:`InputEvent`\ ) |const| | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`move_to_front`\ (\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`queue_redraw`\ (\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_notify_local_transform`\ (\ enable\: :ref:`bool`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_notify_transform`\ (\ enable\: :ref:`bool`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_visibility_layer_bit`\ (\ layer\: :ref:`int`, enabled\: :ref:`bool`\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`show`\ (\ ) | - +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_draw`\ (\ ) |virtual| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_animation_slice`\ (\ animation_length\: :ref:`float`, slice_begin\: :ref:`float`, slice_end\: :ref:`float`, offset\: :ref:`float` = 0.0\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_arc`\ (\ center\: :ref:`Vector2`, radius\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_char`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_char_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, size\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_circle`\ (\ position\: :ref:`Vector2`, radius\: :ref:`float`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_colored_polygon`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_dashed_line`\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, dash\: :ref:`float` = 2.0, aligned\: :ref:`bool` = true, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_end_animation`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_lcd_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_line`\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_mesh`\ (\ mesh\: :ref:`Mesh`, texture\: :ref:`Texture2D`, transform\: :ref:`Transform2D` = Transform2D(1, 0, 0, 1, 0, 0), modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_msdf_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), outline\: :ref:`float` = 0.0, pixel_range\: :ref:`float` = 4.0, scale\: :ref:`float` = 1.0\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline_colors`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline_string`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multiline_string_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_multimesh`\ (\ multimesh\: :ref:`MultiMesh`, texture\: :ref:`Texture2D`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_polygon`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_polyline`\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_polyline_colors`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_primitive`\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array`, texture\: :ref:`Texture2D` = null\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_rect`\ (\ rect\: :ref:`Rect2`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_set_transform`\ (\ position\: :ref:`Vector2`, rotation\: :ref:`float` = 0.0, scale\: :ref:`Vector2` = Vector2(1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_set_transform_matrix`\ (\ xform\: :ref:`Transform2D`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_string`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_string_outline`\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_style_box`\ (\ style_box\: :ref:`StyleBox`, rect\: :ref:`Rect2`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_texture`\ (\ texture\: :ref:`Texture2D`, position\: :ref:`Vector2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_texture_rect`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, tile\: :ref:`bool`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`draw_texture_rect_region`\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false, clip_uv\: :ref:`bool` = true\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`force_update_transform`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_canvas`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_canvas_item`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`CanvasLayer` | :ref:`get_canvas_layer_node`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_canvas_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_global_mouse_position`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_global_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_global_transform_with_canvas`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get_instance_shader_parameter`\ (\ name\: :ref:`StringName`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_local_mouse_position`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_screen_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Rect2` | :ref:`get_viewport_rect`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform2D` | :ref:`get_viewport_transform`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_visibility_layer_bit`\ (\ layer\: :ref:`int`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`World2D` | :ref:`get_world_2d`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`hide`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_local_transform_notification_enabled`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_transform_notification_enabled`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_visible_in_tree`\ (\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`make_canvas_position_local`\ (\ viewport_point\: :ref:`Vector2`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`InputEvent` | :ref:`make_input_local`\ (\ event\: :ref:`InputEvent`\ ) |const| | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_to_front`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`queue_redraw`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_instance_shader_parameter`\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_notify_local_transform`\ (\ enable\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_notify_transform`\ (\ enable\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_visibility_layer_bit`\ (\ layer\: :ref:`int`, enabled\: :ref:`bool`\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`show`\ (\ ) | + +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -219,9 +225,9 @@ Signals .. rst-class:: classref-signal -**draw**\ (\ ) +**draw**\ (\ ) :ref:`🔗` -Emitted when the **CanvasItem** must redraw, *after* the related :ref:`NOTIFICATION_DRAW` notification, and *before* :ref:`_draw` is called. +Emitted when the **CanvasItem** must redraw, *after* the related :ref:`NOTIFICATION_DRAW` notification, and *before* :ref:`_draw()` is called. \ **Note:** Deferred connections do not allow drawing through the ``draw_*`` methods. @@ -233,9 +239,9 @@ Emitted when the **CanvasItem** must redraw, *after* the related :ref:`NOTIFICAT .. rst-class:: classref-signal -**hidden**\ (\ ) +**hidden**\ (\ ) :ref:`🔗` -Emitted when becoming hidden. +Emitted when this node becomes hidden, i.e. it's no longer visible in the tree (see :ref:`is_visible_in_tree()`). .. rst-class:: classref-item-separator @@ -245,9 +251,9 @@ Emitted when becoming hidden. .. rst-class:: classref-signal -**item_rect_changed**\ (\ ) +**item_rect_changed**\ (\ ) :ref:`🔗` -Emitted when the item's :ref:`Rect2` boundaries (position or size) have changed, or when an action is taking place that may have impacted these boundaries (e.g. changing :ref:`Sprite2D.texture`). +Emitted when the **CanvasItem**'s boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing :ref:`Sprite2D.texture`). .. rst-class:: classref-item-separator @@ -257,9 +263,11 @@ Emitted when the item's :ref:`Rect2` boundaries (position or size) .. rst-class:: classref-signal -**visibility_changed**\ (\ ) +**visibility_changed**\ (\ ) :ref:`🔗` + +Emitted when the **CanvasItem**'s visibility changes, either because its own :ref:`visible` property changed or because its visibility in the tree changed (see :ref:`is_visible_in_tree()`). -Emitted when the visibility (hidden/visible) changes. +This signal is emitted *after* the related :ref:`NOTIFICATION_VISIBILITY_CHANGED` notification. .. rst-class:: classref-section-separator @@ -274,7 +282,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **TextureFilter**: +enum **TextureFilter**: :ref:`🔗` .. _class_CanvasItem_constant_TEXTURE_FILTER_PARENT_NODE: @@ -356,7 +364,7 @@ Represents the size of the :ref:`TextureFilter` e .. rst-class:: classref-enumeration -enum **TextureRepeat**: +enum **TextureRepeat**: :ref:`🔗` .. _class_CanvasItem_constant_TEXTURE_REPEAT_PARENT_NODE: @@ -372,7 +380,7 @@ The **CanvasItem** will inherit the filter from its parent. :ref:`TextureRepeat` **TEXTURE_REPEAT_DISABLED** = ``1`` -Texture will not repeat. +The texture does not repeat. Sampling the texture outside its extents will result in "stretching" of the edge pixels. You can avoid this by ensuring a 1-pixel fully transparent border on each side of the texture. .. _class_CanvasItem_constant_TEXTURE_REPEAT_ENABLED: @@ -380,7 +388,7 @@ Texture will not repeat. :ref:`TextureRepeat` **TEXTURE_REPEAT_ENABLED** = ``2`` -Texture will repeat normally. +The texture repeats when exceeding the texture's size. .. _class_CanvasItem_constant_TEXTURE_REPEAT_MIRROR: @@ -388,7 +396,7 @@ Texture will repeat normally. :ref:`TextureRepeat` **TEXTURE_REPEAT_MIRROR** = ``3`` -Texture will repeat in a 2×2 tiled mode, where elements at even positions are mirrored. +The texture repeats when the exceeding the texture's size in a "2×2 tiled mode". Repeated textures at even positions are mirrored. .. _class_CanvasItem_constant_TEXTURE_REPEAT_MAX: @@ -406,7 +414,7 @@ Represents the size of the :ref:`TextureRepeat` e .. rst-class:: classref-enumeration -enum **ClipChildrenMode**: +enum **ClipChildrenMode**: :ref:`🔗` .. _class_CanvasItem_constant_CLIP_CHILDREN_DISABLED: @@ -414,7 +422,7 @@ enum **ClipChildrenMode**: :ref:`ClipChildrenMode` **CLIP_CHILDREN_DISABLED** = ``0`` -Child draws over parent and is not clipped. +Children are drawn over this node and are not clipped. .. _class_CanvasItem_constant_CLIP_CHILDREN_ONLY: @@ -422,7 +430,7 @@ Child draws over parent and is not clipped. :ref:`ClipChildrenMode` **CLIP_CHILDREN_ONLY** = ``1`` -Parent is used for the purposes of clipping only. Child is clipped to the parent's visible area, parent is not drawn. +This node is used as a mask and is **not** drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to this node's drawn area. .. _class_CanvasItem_constant_CLIP_CHILDREN_AND_DRAW: @@ -430,7 +438,7 @@ Parent is used for the purposes of clipping only. Child is clipped to the parent :ref:`ClipChildrenMode` **CLIP_CHILDREN_AND_DRAW** = ``2`` -Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area. +This node is used as a mask and is also drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to the parent's drawn area. .. _class_CanvasItem_constant_CLIP_CHILDREN_MAX: @@ -453,39 +461,45 @@ Constants .. rst-class:: classref-constant -**NOTIFICATION_TRANSFORM_CHANGED** = ``2000`` +**NOTIFICATION_TRANSFORM_CHANGED** = ``2000`` :ref:`🔗` -The **CanvasItem**'s global transform has changed. This notification is only received if enabled by :ref:`set_notify_transform`. +Notification received when this node's global transform changes, if :ref:`is_transform_notification_enabled()` is ``true``. See also :ref:`set_notify_transform()` and :ref:`get_transform()`. + +\ **Note:** Many canvas items such as :ref:`Camera2D` or :ref:`CollisionObject2D` automatically enable this in order to function correctly. .. _class_CanvasItem_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED: .. rst-class:: classref-constant -**NOTIFICATION_LOCAL_TRANSFORM_CHANGED** = ``35`` +**NOTIFICATION_LOCAL_TRANSFORM_CHANGED** = ``35`` :ref:`🔗` + +Notification received when this node's transform changes, if :ref:`is_local_transform_notification_enabled()` is ``true``. This is not received when a parent :ref:`Node2D`'s transform changes. See also :ref:`set_notify_local_transform()`. -The **CanvasItem**'s local transform has changed. This notification is only received if enabled by :ref:`set_notify_local_transform`. +\ **Note:** Many canvas items such as :ref:`Camera2D` or :ref:`CollisionShape2D` automatically enable this in order to function correctly. .. _class_CanvasItem_constant_NOTIFICATION_DRAW: .. rst-class:: classref-constant -**NOTIFICATION_DRAW** = ``30`` +**NOTIFICATION_DRAW** = ``30`` :ref:`🔗` -The **CanvasItem** is requested to draw (see :ref:`_draw`). +The **CanvasItem** is requested to draw (see :ref:`_draw()`). .. _class_CanvasItem_constant_NOTIFICATION_VISIBILITY_CHANGED: .. rst-class:: classref-constant -**NOTIFICATION_VISIBILITY_CHANGED** = ``31`` +**NOTIFICATION_VISIBILITY_CHANGED** = ``31`` :ref:`🔗` -The **CanvasItem**'s visibility has changed. +Notification received when this node's visibility changes (see :ref:`visible` and :ref:`is_visible_in_tree()`). + +This notification is received *before* the related :ref:`visibility_changed` signal. .. _class_CanvasItem_constant_NOTIFICATION_ENTER_CANVAS: .. rst-class:: classref-constant -**NOTIFICATION_ENTER_CANVAS** = ``32`` +**NOTIFICATION_ENTER_CANVAS** = ``32`` :ref:`🔗` The **CanvasItem** has entered the canvas. @@ -493,7 +507,7 @@ The **CanvasItem** has entered the canvas. .. rst-class:: classref-constant -**NOTIFICATION_EXIT_CANVAS** = ``33`` +**NOTIFICATION_EXIT_CANVAS** = ``33`` :ref:`🔗` The **CanvasItem** has exited the canvas. @@ -501,9 +515,9 @@ The **CanvasItem** has exited the canvas. .. rst-class:: classref-constant -**NOTIFICATION_WORLD_2D_CHANGED** = ``36`` +**NOTIFICATION_WORLD_2D_CHANGED** = ``36`` :ref:`🔗` -The **CanvasItem**'s active :ref:`World2D` changed. +Notification received when this **CanvasItem** is registered to a new :ref:`World2D` (see :ref:`get_world_2d()`). .. rst-class:: classref-section-separator @@ -518,14 +532,16 @@ Property Descriptions .. rst-class:: classref-property -:ref:`ClipChildrenMode` **clip_children** = ``0`` +:ref:`ClipChildrenMode` **clip_children** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_clip_children_mode**\ (\ value\: :ref:`ClipChildrenMode`\ ) - :ref:`ClipChildrenMode` **get_clip_children_mode**\ (\ ) -Allows the current node to clip child nodes, essentially acting as a mask. +The mode in which this node clips its children, acting as a mask. + +\ **Note:** Clipping nodes cannot be nested or placed within a :ref:`CanvasGroup`. If an ancestor of this node clips its children or is a :ref:`CanvasGroup`, then this node's clip mode should be set to :ref:`CLIP_CHILDREN_DISABLED` to avoid unexpected behavior. .. rst-class:: classref-item-separator @@ -535,7 +551,7 @@ Allows the current node to clip child nodes, essentially acting as a mask. .. rst-class:: classref-property -:ref:`int` **light_mask** = ``1`` +:ref:`int` **light_mask** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -552,7 +568,7 @@ The rendering layers in which this **CanvasItem** responds to :ref:`Light2D` **material** +:ref:`Material` **material** :ref:`🔗` .. rst-class:: classref-property-setget @@ -569,7 +585,7 @@ The material applied to this **CanvasItem**. .. rst-class:: classref-property -:ref:`Color` **modulate** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **modulate** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -586,7 +602,7 @@ The color applied to this **CanvasItem**. This property does affect child **Canv .. rst-class:: classref-property -:ref:`Color` **self_modulate** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **self_modulate** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -595,7 +611,7 @@ The color applied to this **CanvasItem**. This property does affect child **Canv The color applied to this **CanvasItem**. This property does **not** affect child **CanvasItem**\ s, unlike :ref:`modulate` which affects both the node itself and its children. -\ **Note:** Internal children (e.g. sliders in :ref:`ColorPicker` or tab bar in :ref:`TabContainer`) are also not affected by this property (see ``include_internal`` parameter of :ref:`Node.get_child` and other similar methods). +\ **Note:** Internal children are also not affected by this property (see the ``include_internal`` parameter in :ref:`Node.add_child()`). For built-in nodes this includes sliders in :ref:`ColorPicker`, and the tab bar in :ref:`TabContainer`. .. rst-class:: classref-item-separator @@ -605,14 +621,14 @@ The color applied to this **CanvasItem**. This property does **not** affect chil .. rst-class:: classref-property -:ref:`bool` **show_behind_parent** = ``false`` +:ref:`bool` **show_behind_parent** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_draw_behind_parent**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_draw_behind_parent_enabled**\ (\ ) -If ``true``, the object draws behind its parent. +If ``true``, this node draws behind its parent. .. rst-class:: classref-item-separator @@ -622,14 +638,14 @@ If ``true``, the object draws behind its parent. .. rst-class:: classref-property -:ref:`TextureFilter` **texture_filter** = ``0`` +:ref:`TextureFilter` **texture_filter** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_texture_filter**\ (\ value\: :ref:`TextureFilter`\ ) - :ref:`TextureFilter` **get_texture_filter**\ (\ ) -The texture filtering mode to use on this **CanvasItem**. +The filtering mode used to render this **CanvasItem**'s texture(s). .. rst-class:: classref-item-separator @@ -639,14 +655,16 @@ The texture filtering mode to use on this **CanvasItem**. .. rst-class:: classref-property -:ref:`TextureRepeat` **texture_repeat** = ``0`` +:ref:`TextureRepeat` **texture_repeat** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_texture_repeat**\ (\ value\: :ref:`TextureRepeat`\ ) - :ref:`TextureRepeat` **get_texture_repeat**\ (\ ) -The texture repeating mode to use on this **CanvasItem**. +The repeating mode used to render this **CanvasItem**'s texture(s). It affects what happens when the texture is sampled outside its extents, for example by setting a :ref:`Sprite2D.region_rect` that is larger than the texture or assigning :ref:`Polygon2D` UV points outside the texture. + +\ **Note:** :ref:`TextureRect` is not affected by :ref:`texture_repeat`, as it uses its own texture repeating implementation. .. rst-class:: classref-item-separator @@ -656,7 +674,7 @@ The texture repeating mode to use on this **CanvasItem**. .. rst-class:: classref-property -:ref:`bool` **top_level** = ``false`` +:ref:`bool` **top_level** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -673,14 +691,14 @@ If ``true``, this **CanvasItem** will *not* inherit its transform from parent ** .. rst-class:: classref-property -:ref:`bool` **use_parent_material** = ``false`` +:ref:`bool` **use_parent_material** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_use_parent_material**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_use_parent_material**\ (\ ) -If ``true``, the parent **CanvasItem**'s :ref:`material` property is used as this one's material. +If ``true``, the parent **CanvasItem**'s :ref:`material` is used as this node's material. .. rst-class:: classref-item-separator @@ -690,7 +708,7 @@ If ``true``, the parent **CanvasItem**'s :ref:`material` **visibility_layer** = ``1`` +:ref:`int` **visibility_layer** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -707,14 +725,14 @@ The rendering layer in which this **CanvasItem** is rendered by :ref:`Viewport` **visible** = ``true`` +:ref:`bool` **visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_visible**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_visible**\ (\ ) -If ``true``, this **CanvasItem** is drawn. The node is only visible if all of its ancestors are visible as well (in other words, :ref:`is_visible_in_tree` must return ``true``). +If ``true``, this **CanvasItem** may be drawn. Whether this **CanvasItem** is actually drawn depends on the visibility of all of its **CanvasItem** ancestors. In other words: this **CanvasItem** will be drawn when :ref:`is_visible_in_tree()` returns ``true`` and all **CanvasItem** ancestors share at least one :ref:`visibility_layer` with this **CanvasItem**. \ **Note:** For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. @@ -726,16 +744,18 @@ If ``true``, this **CanvasItem** is drawn. The node is only visible if all of it .. rst-class:: classref-property -:ref:`bool` **y_sort_enabled** = ``false`` +:ref:`bool` **y_sort_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_y_sort_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_y_sort_enabled**\ (\ ) -If ``true``, this **CanvasItem** and its **CanvasItem** child nodes are sorted according to the Y position. Nodes with a lower Y position are drawn before those with a higher Y position. If ``false``, Y-sorting is disabled. +If ``true``, this and child **CanvasItem** nodes with a higher Y position are rendered in front of nodes with a lower Y position. If ``false``, this and child **CanvasItem** nodes are rendered normally in scene tree order. -You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same space as the parent Y-sort. This feature allows you to organize a scene better or divide it into multiple ones without changing your scene tree. +With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc.) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree. + +Nodes sort relative to each other only if they are on the same :ref:`z_index`. .. rst-class:: classref-item-separator @@ -745,14 +765,16 @@ You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same s .. rst-class:: classref-property -:ref:`bool` **z_as_relative** = ``true`` +:ref:`bool` **z_as_relative** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_z_as_relative**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_z_relative**\ (\ ) -If ``true``, the node's Z index is relative to its parent's Z index. If this node's Z index is 2 and its parent's effective Z index is 3, then this node's effective Z index will be 2 + 3 = 5. +If ``true``, this node's final Z index is relative to its parent's Z index. + +For example, if :ref:`z_index` is ``2`` and its parent's final Z index is ``3``, then this node's final Z index will be ``5`` (``2 + 3``). .. rst-class:: classref-item-separator @@ -762,16 +784,16 @@ If ``true``, the node's Z index is relative to its parent's Z index. If this nod .. rst-class:: classref-property -:ref:`int` **z_index** = ``0`` +:ref:`int` **z_index** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_z_index**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_z_index**\ (\ ) -Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between :ref:`RenderingServer.CANVAS_ITEM_Z_MIN` and :ref:`RenderingServer.CANVAS_ITEM_Z_MAX` (inclusive). +The order in which this node is drawn. A node with a higher Z index will display in front of others. Must be between :ref:`RenderingServer.CANVAS_ITEM_Z_MIN` and :ref:`RenderingServer.CANVAS_ITEM_Z_MAX` (inclusive). -\ **Note:** Changing the Z index of a :ref:`Control` only affects the drawing order, not the order in which input events are handled. This can be useful to implement certain UI animations, e.g. a menu where hovered items are scaled and should overlap others. +\ **Note:** The Z index does **not** affect the order in which **CanvasItem** nodes are processed or the way input events are handled. This is especially important to keep in mind for :ref:`Control` nodes. .. rst-class:: classref-section-separator @@ -786,11 +808,11 @@ Method Descriptions .. rst-class:: classref-method -|void| **_draw**\ (\ ) |virtual| +|void| **_draw**\ (\ ) |virtual| :ref:`🔗` -Called when **CanvasItem** has been requested to redraw (after :ref:`queue_redraw` is called, either manually or by the engine). +Called when **CanvasItem** has been requested to redraw (after :ref:`queue_redraw()` is called, either manually or by the engine). -Corresponds to the :ref:`NOTIFICATION_DRAW` notification in :ref:`Object._notification`. +Corresponds to the :ref:`NOTIFICATION_DRAW` notification in :ref:`Object._notification()`. .. rst-class:: classref-item-separator @@ -800,7 +822,7 @@ Corresponds to the :ref:`NOTIFICATION_DRAW`, slice_begin\: :ref:`float`, slice_end\: :ref:`float`, offset\: :ref:`float` = 0.0\ ) +|void| **draw_animation_slice**\ (\ animation_length\: :ref:`float`, slice_begin\: :ref:`float`, slice_end\: :ref:`float`, offset\: :ref:`float` = 0.0\ ) :ref:`🔗` Subsequent drawing commands will be ignored unless they fall within the specified animation slice. This is a faster way to implement animations that loop on background rather than redrawing constantly. @@ -812,9 +834,9 @@ Subsequent drawing commands will be ignored unless they fall within the specifie .. rst-class:: classref-method -|void| **draw_arc**\ (\ center\: :ref:`Vector2`, radius\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) +|void| **draw_arc**\ (\ center\: :ref:`Vector2`, radius\: :ref:`float`, start_angle\: :ref:`float`, end_angle\: :ref:`float`, point_count\: :ref:`int`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws an unfilled arc between the given angles with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). The larger the value of ``point_count``, the smoother the curve. See also :ref:`draw_circle`. +Draws an unfilled arc between the given angles with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). The larger the value of ``point_count``, the smoother the curve. See also :ref:`draw_circle()`. If ``width`` is negative, it will be ignored and the arc will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. @@ -828,9 +850,9 @@ The arc is drawn from ``start_angle`` towards the value of ``end_angle`` so in c .. rst-class:: classref-method -|void| **draw_char**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| +|void| **draw_char**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` -Draws a string first character using a custom font. +Draws a string first character using a custom font. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. .. rst-class:: classref-item-separator @@ -840,9 +862,9 @@ Draws a string first character using a custom font. .. rst-class:: classref-method -|void| **draw_char_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, size\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| +|void| **draw_char_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, char\: :ref:`String`, font_size\: :ref:`int` = 16, size\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` -Draws a string first character outline using a custom font. +Draws a string first character outline using a custom font. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. .. rst-class:: classref-item-separator @@ -852,9 +874,17 @@ Draws a string first character outline using a custom font. .. rst-class:: classref-method -|void| **draw_circle**\ (\ position\: :ref:`Vector2`, radius\: :ref:`float`, color\: :ref:`Color`\ ) +|void| **draw_circle**\ (\ position\: :ref:`Vector2`, radius\: :ref:`float`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` + +Draws a circle. See also :ref:`draw_arc()`, :ref:`draw_polyline()`, and :ref:`draw_polygon()`. + +If ``filled`` is ``true``, the circle will be filled with the ``color`` specified. If ``filled`` is ``false``, the circle will be drawn as a stroke with the ``color`` and ``width`` specified. + +If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. + +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. -Draws a colored, filled circle. See also :ref:`draw_arc`, :ref:`draw_polyline` and :ref:`draw_polygon`. +\ **Note:** ``width`` is only effective if ``filled`` is ``false``. .. rst-class:: classref-item-separator @@ -864,9 +894,11 @@ Draws a colored, filled circle. See also :ref:`draw_arc`, color\: :ref:`Color`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) +|void| **draw_colored_polygon**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) :ref:`🔗` + +Draws a colored polygon of any number of points, convex or concave. Unlike :ref:`draw_polygon()`, a single color must be specified for the whole polygon. -Draws a colored polygon of any number of points, convex or concave. Unlike :ref:`draw_polygon`, a single color must be specified for the whole polygon. +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with :ref:`Geometry2D.triangulate_polygon()` and using :ref:`draw_mesh()`, :ref:`draw_multimesh()`, or :ref:`RenderingServer.canvas_item_add_triangle_array()`. .. rst-class:: classref-item-separator @@ -876,12 +908,18 @@ Draws a colored polygon of any number of points, convex or concave. Unlike :ref: .. rst-class:: classref-method -|void| **draw_dashed_line**\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, dash\: :ref:`float` = 2.0, aligned\: :ref:`bool` = true\ ) +|void| **draw_dashed_line**\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, dash\: :ref:`float` = 2.0, aligned\: :ref:`bool` = true, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws a dashed line from a 2D point to another, with a given color and width. See also :ref:`draw_multiline` and :ref:`draw_polyline`. +Draws a dashed line from a 2D point to another, with a given color and width. See also :ref:`draw_line()`, :ref:`draw_multiline()`, and :ref:`draw_polyline()`. If ``width`` is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. +\ ``dash`` is the length of each dash in pixels, with the gap between each dash being the same length. If ``aligned`` is ``true``, the length of the first and last dashes may be shortened or lengthened to allow the line to begin and end at the precise points defined by ``from`` and ``to``. Both ends are always symmetrical when ``aligned`` is ``true``. If ``aligned`` is ``false``, all dashes will have the same length, but the line may appear incomplete at the end due to the dash length not dividing evenly into the line length. Only full dashes are drawn when ``aligned`` is ``false``. + +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + +\ **Note:** ``antialiased`` is only effective if ``width`` is greater than ``0.0``. + .. rst-class:: classref-item-separator ---- @@ -890,9 +928,9 @@ If ``width`` is negative, then a two-point primitives will be drawn instead of a .. rst-class:: classref-method -|void| **draw_end_animation**\ (\ ) +|void| **draw_end_animation**\ (\ ) :ref:`🔗` -After submitting all animations slices via :ref:`draw_animation_slice`, this function can be used to revert drawing to its default state (all subsequent drawing commands will be visible). If you don't care about this particular use case, usage of this function after submitting the slices is not required. +After submitting all animations slices via :ref:`draw_animation_slice()`, this function can be used to revert drawing to its default state (all subsequent drawing commands will be visible). If you don't care about this particular use case, usage of this function after submitting the slices is not required. .. rst-class:: classref-item-separator @@ -902,7 +940,7 @@ After submitting all animations slices via :ref:`draw_animation_slice`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) +|void| **draw_lcd_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) :ref:`🔗` Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color. @@ -923,9 +961,9 @@ Texture is drawn using the following blend operation, blend mode of the :ref:`Ca .. rst-class:: classref-method -|void| **draw_line**\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) +|void| **draw_line**\ (\ from\: :ref:`Vector2`, to\: :ref:`Vector2`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also :ref:`draw_multiline` and :ref:`draw_polyline`. +Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also :ref:`draw_dashed_line()`, :ref:`draw_multiline()`, and :ref:`draw_polyline()`. If ``width`` is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. @@ -937,7 +975,7 @@ If ``width`` is negative, then a two-point primitive will be drawn instead of a .. rst-class:: classref-method -|void| **draw_mesh**\ (\ mesh\: :ref:`Mesh`, texture\: :ref:`Texture2D`, transform\: :ref:`Transform2D` = Transform2D(1, 0, 0, 1, 0, 0), modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) +|void| **draw_mesh**\ (\ mesh\: :ref:`Mesh`, texture\: :ref:`Texture2D`, transform\: :ref:`Transform2D` = Transform2D(1, 0, 0, 1, 0, 0), modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) :ref:`🔗` Draws a :ref:`Mesh` in 2D, using the provided texture. See :ref:`MeshInstance2D` for related documentation. @@ -949,9 +987,9 @@ Draws a :ref:`Mesh` in 2D, using the provided texture. See :ref:`Mes .. rst-class:: classref-method -|void| **draw_msdf_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), outline\: :ref:`float` = 0.0, pixel_range\: :ref:`float` = 4.0, scale\: :ref:`float` = 1.0\ ) +|void| **draw_msdf_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), outline\: :ref:`float` = 0.0, pixel_range\: :ref:`float` = 4.0, scale\: :ref:`float` = 1.0\ ) :ref:`🔗` -Draws a textured rectangle region of the multi-channel signed distance field texture at a given position, optionally modulated by a color. See :ref:`FontFile.multichannel_signed_distance_field` for more information and caveats about MSDF font rendering. +Draws a textured rectangle region of the multichannel signed distance field texture at a given position, optionally modulated by a color. See :ref:`FontFile.multichannel_signed_distance_field` for more information and caveats about MSDF font rendering. If ``outline`` is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the ``outline`` radius. @@ -965,12 +1003,14 @@ Value of the ``pixel_range`` should the same that was used during distance field .. rst-class:: classref-method -|void| **draw_multiline**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0\ ) +|void| **draw_multiline**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws multiple disconnected lines with a uniform ``width`` and ``color``. Each line is defined by two consecutive points from ``points`` array, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line` calls. To draw interconnected lines, use :ref:`draw_polyline` instead. +Draws multiple disconnected lines with a uniform ``width`` and ``color``. Each line is defined by two consecutive points from ``points`` array, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw interconnected lines, use :ref:`draw_polyline()` instead. If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. +\ **Note:** ``antialiased`` is only effective if ``width`` is greater than ``0.0``. + .. rst-class:: classref-item-separator ---- @@ -979,12 +1019,14 @@ If ``width`` is negative, then two-point primitives will be drawn instead of a f .. rst-class:: classref-method -|void| **draw_multiline_colors**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0\ ) +|void| **draw_multiline_colors**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws multiple disconnected lines with a uniform ``width`` and segment-by-segment coloring. Each segment is defined by two consecutive points from ``points`` array and a corresponding color from ``colors`` array, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints and has ``colors[i]`` color. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line` calls. To draw interconnected lines, use :ref:`draw_polyline_colors` instead. +Draws multiple disconnected lines with a uniform ``width`` and segment-by-segment coloring. Each segment is defined by two consecutive points from ``points`` array and a corresponding color from ``colors`` array, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints and has ``colors[i]`` color. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw interconnected lines, use :ref:`draw_polyline_colors()` instead. If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. +\ **Note:** ``antialiased`` is only effective if ``width`` is greater than ``0.0``. + .. rst-class:: classref-item-separator ---- @@ -993,9 +1035,9 @@ If ``width`` is negative, then two-point primitives will be drawn instead of a f .. rst-class:: classref-method -|void| **draw_multiline_string**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| +|void| **draw_multiline_string**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` -Breaks ``text`` into lines and draws it using the specified ``font`` at the ``pos`` (top-left corner). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. +Breaks ``text`` into lines and draws it using the specified ``font`` at the ``pos`` (top-left corner). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. .. rst-class:: classref-item-separator @@ -1005,9 +1047,9 @@ Breaks ``text`` into lines and draws it using the specified ``font`` at the ``po .. rst-class:: classref-method -|void| **draw_multiline_string_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| +|void| **draw_multiline_string_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, max_lines\: :ref:`int` = -1, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), brk_flags\: |bitfield|\[:ref:`LineBreakFlag`\] = 3, justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` -Breaks ``text`` to the lines and draws text outline using the specified ``font`` at the ``pos`` (top-left corner). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. +Breaks ``text`` to the lines and draws text outline using the specified ``font`` at the ``pos`` (top-left corner). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. .. rst-class:: classref-item-separator @@ -1017,7 +1059,7 @@ Breaks ``text`` to the lines and draws text outline using the specified ``font`` .. rst-class:: classref-method -|void| **draw_multimesh**\ (\ multimesh\: :ref:`MultiMesh`, texture\: :ref:`Texture2D`\ ) +|void| **draw_multimesh**\ (\ multimesh\: :ref:`MultiMesh`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` Draws a :ref:`MultiMesh` in 2D with the provided texture. See :ref:`MultiMeshInstance2D` for related documentation. @@ -1029,9 +1071,11 @@ Draws a :ref:`MultiMesh` in 2D with the provided texture. See : .. rst-class:: classref-method -|void| **draw_polygon**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) +|void| **draw_polygon**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array` = PackedVector2Array(), texture\: :ref:`Texture2D` = null\ ) :ref:`🔗` -Draws a solid polygon of any number of points, convex or concave. Unlike :ref:`draw_colored_polygon`, each point's color can be changed individually. See also :ref:`draw_polyline` and :ref:`draw_polyline_colors`. If you need more flexibility (such as being able to use bones), use :ref:`RenderingServer.canvas_item_add_triangle_array` instead. +Draws a solid polygon of any number of points, convex or concave. Unlike :ref:`draw_colored_polygon()`, each point's color can be changed individually. See also :ref:`draw_polyline()` and :ref:`draw_polyline_colors()`. If you need more flexibility (such as being able to use bones), use :ref:`RenderingServer.canvas_item_add_triangle_array()` instead. + +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with :ref:`Geometry2D.triangulate_polygon()` and using :ref:`draw_mesh()`, :ref:`draw_multimesh()`, or :ref:`RenderingServer.canvas_item_add_triangle_array()`. .. rst-class:: classref-item-separator @@ -1041,9 +1085,9 @@ Draws a solid polygon of any number of points, convex or concave. Unlike :ref:`d .. rst-class:: classref-method -|void| **draw_polyline**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) +|void| **draw_polyline**\ (\ points\: :ref:`PackedVector2Array`, color\: :ref:`Color`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws interconnected line segments with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). When drawing large amounts of lines, this is faster than using individual :ref:`draw_line` calls. To draw disconnected lines, use :ref:`draw_multiline` instead. See also :ref:`draw_polygon`. +Draws interconnected line segments with a uniform ``color`` and ``width`` and optional antialiasing (supported only for positive ``width``). When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw disconnected lines, use :ref:`draw_multiline()` instead. See also :ref:`draw_polygon()`. If ``width`` is negative, it will be ignored and the polyline will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. @@ -1055,9 +1099,9 @@ If ``width`` is negative, it will be ignored and the polyline will be drawn usin .. rst-class:: classref-method -|void| **draw_polyline_colors**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) +|void| **draw_polyline_colors**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws interconnected line segments with a uniform ``width``, point-by-point coloring, and optional antialiasing (supported only for positive ``width``). Colors assigned to line points match by index between ``points`` and ``colors``, i.e. each line segment is filled with a gradient between the colors of the endpoints. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line` calls. To draw disconnected lines, use :ref:`draw_multiline_colors` instead. See also :ref:`draw_polygon`. +Draws interconnected line segments with a uniform ``width``, point-by-point coloring, and optional antialiasing (supported only for positive ``width``). Colors assigned to line points match by index between ``points`` and ``colors``, i.e. each line segment is filled with a gradient between the colors of the endpoints. When drawing large amounts of lines, this is faster than using individual :ref:`draw_line()` calls. To draw disconnected lines, use :ref:`draw_multiline_colors()` instead. See also :ref:`draw_polygon()`. If ``width`` is negative, it will be ignored and the polyline will be drawn using :ref:`RenderingServer.PRIMITIVE_LINE_STRIP`. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. @@ -1069,9 +1113,9 @@ If ``width`` is negative, it will be ignored and the polyline will be drawn usin .. rst-class:: classref-method -|void| **draw_primitive**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array`, texture\: :ref:`Texture2D` = null\ ) +|void| **draw_primitive**\ (\ points\: :ref:`PackedVector2Array`, colors\: :ref:`PackedColorArray`, uvs\: :ref:`PackedVector2Array`, texture\: :ref:`Texture2D` = null\ ) :ref:`🔗` -Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. If 0 points or more than 4 points are specified, nothing will be drawn and an error message will be printed. See also :ref:`draw_line`, :ref:`draw_polyline`, :ref:`draw_polygon`, and :ref:`draw_rect`. +Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. If 0 points or more than 4 points are specified, nothing will be drawn and an error message will be printed. See also :ref:`draw_line()`, :ref:`draw_polyline()`, :ref:`draw_polygon()`, and :ref:`draw_rect()`. .. rst-class:: classref-item-separator @@ -1081,12 +1125,14 @@ Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for .. rst-class:: classref-method -|void| **draw_rect**\ (\ rect\: :ref:`Rect2`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0\ ) +|void| **draw_rect**\ (\ rect\: :ref:`Rect2`, color\: :ref:`Color`, filled\: :ref:`bool` = true, width\: :ref:`float` = -1.0, antialiased\: :ref:`bool` = false\ ) :ref:`🔗` -Draws a rectangle. If ``filled`` is ``true``, the rectangle will be filled with the ``color`` specified. If ``filled`` is ``false``, the rectangle will be drawn as a stroke with the ``color`` and ``width`` specified. See also :ref:`draw_texture_rect`. +Draws a rectangle. If ``filled`` is ``true``, the rectangle will be filled with the ``color`` specified. If ``filled`` is ``false``, the rectangle will be drawn as a stroke with the ``color`` and ``width`` specified. See also :ref:`draw_texture_rect()`. If ``width`` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive ``width`` like ``1.0``. +If ``antialiased`` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + \ **Note:** ``width`` is only effective if ``filled`` is ``false``. \ **Note:** Unfilled rectangles drawn with a negative ``width`` may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent ``color``). @@ -1099,7 +1145,7 @@ If ``width`` is negative, then two-point primitives will be drawn instead of a f .. rst-class:: classref-method -|void| **draw_set_transform**\ (\ position\: :ref:`Vector2`, rotation\: :ref:`float` = 0.0, scale\: :ref:`Vector2` = Vector2(1, 1)\ ) +|void| **draw_set_transform**\ (\ position\: :ref:`Vector2`, rotation\: :ref:`float` = 0.0, scale\: :ref:`Vector2` = Vector2(1, 1)\ ) :ref:`🔗` Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this. @@ -1113,7 +1159,7 @@ Sets a custom transform for drawing via components. Anything drawn afterwards wi .. rst-class:: classref-method -|void| **draw_set_transform_matrix**\ (\ xform\: :ref:`Transform2D`\ ) +|void| **draw_set_transform_matrix**\ (\ xform\: :ref:`Transform2D`\ ) :ref:`🔗` Sets a custom transform for drawing via matrix. Anything drawn afterwards will be transformed by this. @@ -1125,11 +1171,11 @@ Sets a custom transform for drawing via matrix. Anything drawn afterwards will b .. rst-class:: classref-method -|void| **draw_string**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| +|void| **draw_string**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` -Draws ``text`` using the specified ``font`` at the ``pos`` (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. +Draws ``text`` using the specified ``font`` at the ``pos`` (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. -\ **Example using the default project font:**\ +\ **Example:** Draw "Hello world", using the project's default font: .. tabs:: @@ -1154,7 +1200,7 @@ Draws ``text`` using the specified ``font`` at the ``pos`` (bottom-left corner u -See also :ref:`Font.draw_string`. +See also :ref:`Font.draw_string()`. .. rst-class:: classref-item-separator @@ -1164,9 +1210,9 @@ See also :ref:`Font.draw_string`. .. rst-class:: classref-method -|void| **draw_string_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0\ ) |const| +|void| **draw_string_outline**\ (\ font\: :ref:`Font`, pos\: :ref:`Vector2`, text\: :ref:`String`, alignment\: :ref:`HorizontalAlignment` = 0, width\: :ref:`float` = -1, font_size\: :ref:`int` = 16, size\: :ref:`int` = 1, modulate\: :ref:`Color` = Color(1, 1, 1, 1), justification_flags\: |bitfield|\[:ref:`JustificationFlag`\] = 3, direction\: :ref:`Direction` = 0, orientation\: :ref:`Orientation` = 0, oversampling\: :ref:`float` = 0.0\ ) |const| :ref:`🔗` -Draws ``text`` outline using the specified ``font`` at the ``pos`` (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. +Draws ``text`` outline using the specified ``font`` at the ``pos`` (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If ``oversampling`` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. .. rst-class:: classref-item-separator @@ -1176,7 +1222,7 @@ Draws ``text`` outline using the specified ``font`` at the ``pos`` (bottom-left .. rst-class:: classref-method -|void| **draw_style_box**\ (\ style_box\: :ref:`StyleBox`, rect\: :ref:`Rect2`\ ) +|void| **draw_style_box**\ (\ style_box\: :ref:`StyleBox`, rect\: :ref:`Rect2`\ ) :ref:`🔗` Draws a styled rectangle. @@ -1188,7 +1234,7 @@ Draws a styled rectangle. .. rst-class:: classref-method -|void| **draw_texture**\ (\ texture\: :ref:`Texture2D`, position\: :ref:`Vector2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) +|void| **draw_texture**\ (\ texture\: :ref:`Texture2D`, position\: :ref:`Vector2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1)\ ) :ref:`🔗` Draws a texture at a given position. @@ -1200,9 +1246,9 @@ Draws a texture at a given position. .. rst-class:: classref-method -|void| **draw_texture_rect**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, tile\: :ref:`bool`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false\ ) +|void| **draw_texture_rect**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, tile\: :ref:`bool`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false\ ) :ref:`🔗` -Draws a textured rectangle at a given position, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. See also :ref:`draw_rect` and :ref:`draw_texture_rect_region`. +Draws a textured rectangle at a given position, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. See also :ref:`draw_rect()` and :ref:`draw_texture_rect_region()`. .. rst-class:: classref-item-separator @@ -1212,9 +1258,9 @@ Draws a textured rectangle at a given position, optionally modulated by a color. .. rst-class:: classref-method -|void| **draw_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false, clip_uv\: :ref:`bool` = true\ ) +|void| **draw_texture_rect_region**\ (\ texture\: :ref:`Texture2D`, rect\: :ref:`Rect2`, src_rect\: :ref:`Rect2`, modulate\: :ref:`Color` = Color(1, 1, 1, 1), transpose\: :ref:`bool` = false, clip_uv\: :ref:`bool` = true\ ) :ref:`🔗` -Draws a textured rectangle from a texture's region (specified by ``src_rect``) at a given position, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. See also :ref:`draw_texture_rect`. +Draws a textured rectangle from a texture's region (specified by ``src_rect``) at a given position, optionally modulated by a color. If ``transpose`` is ``true``, the texture will have its X and Y coordinates swapped. See also :ref:`draw_texture_rect()`. .. rst-class:: classref-item-separator @@ -1224,9 +1270,11 @@ Draws a textured rectangle from a texture's region (specified by ``src_rect``) a .. rst-class:: classref-method -|void| **force_update_transform**\ (\ ) +|void| **force_update_transform**\ (\ ) :ref:`🔗` -Forces the transform to update. Transform changes in physics are not instant for performance reasons. Transforms are accumulated and then set. Use this if you need an up-to-date transform when doing physics operations. +Forces the node's transform to update. Fails if the node is not inside the tree. See also :ref:`get_transform()`. + +\ **Note:** For performance reasons, transform changes are usually accumulated and applied *once* at the end of the frame. The update propagates through **CanvasItem** children, as well. Therefore, use this method only when you need an up-to-date transform (such as during physics operations). .. rst-class:: classref-item-separator @@ -1236,9 +1284,9 @@ Forces the transform to update. Transform changes in physics are not instant for .. rst-class:: classref-method -:ref:`RID` **get_canvas**\ (\ ) |const| +:ref:`RID` **get_canvas**\ (\ ) |const| :ref:`🔗` -Returns the :ref:`RID` of the :ref:`World2D` canvas where this item is in. +Returns the :ref:`RID` of the :ref:`World2D` canvas where this node is registered to, used by the :ref:`RenderingServer`. .. rst-class:: classref-item-separator @@ -1248,9 +1296,9 @@ Returns the :ref:`RID` of the :ref:`World2D` canvas wh .. rst-class:: classref-method -:ref:`RID` **get_canvas_item**\ (\ ) |const| +:ref:`RID` **get_canvas_item**\ (\ ) |const| :ref:`🔗` -Returns the canvas item RID used by :ref:`RenderingServer` for this item. +Returns the internal canvas item :ref:`RID` used by the :ref:`RenderingServer` for this node. .. rst-class:: classref-item-separator @@ -1260,7 +1308,7 @@ Returns the canvas item RID used by :ref:`RenderingServer .. rst-class:: classref-method -:ref:`CanvasLayer` **get_canvas_layer_node**\ (\ ) |const| +:ref:`CanvasLayer` **get_canvas_layer_node**\ (\ ) |const| :ref:`🔗` Returns the :ref:`CanvasLayer` that contains this node, or ``null`` if the node is not in any :ref:`CanvasLayer`. @@ -1272,9 +1320,9 @@ Returns the :ref:`CanvasLayer` that contains this node, or `` .. rst-class:: classref-method -:ref:`Transform2D` **get_canvas_transform**\ (\ ) |const| +:ref:`Transform2D` **get_canvas_transform**\ (\ ) |const| :ref:`🔗` -Returns the transform from the coordinate system of the canvas, this item is in, to the :ref:`Viewport`\ s coordinate system. +Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport's coordinate system. See also :ref:`Node.get_viewport()`. .. rst-class:: classref-item-separator @@ -1284,11 +1332,11 @@ Returns the transform from the coordinate system of the canvas, this item is in, .. rst-class:: classref-method -:ref:`Vector2` **get_global_mouse_position**\ (\ ) |const| +:ref:`Vector2` **get_global_mouse_position**\ (\ ) |const| :ref:`🔗` -Returns the mouse's position in the :ref:`CanvasLayer` that this **CanvasItem** is in using the coordinate system of the :ref:`CanvasLayer`. +Returns mouse cursor's global position relative to the :ref:`CanvasLayer` that contains this node. -\ **Note:** For screen-space coordinates (e.g. when using a non-embedded :ref:`Popup`), you can use :ref:`DisplayServer.mouse_get_position`. +\ **Note:** For screen-space coordinates (e.g. when using a non-embedded :ref:`Popup`), you can use :ref:`DisplayServer.mouse_get_position()`. .. rst-class:: classref-item-separator @@ -1298,7 +1346,7 @@ Returns the mouse's position in the :ref:`CanvasLayer` that t .. rst-class:: classref-method -:ref:`Transform2D` **get_global_transform**\ (\ ) |const| +:ref:`Transform2D` **get_global_transform**\ (\ ) |const| :ref:`🔗` Returns the global transform matrix of this item, i.e. the combined transform up to the topmost **CanvasItem** node. The topmost item is a **CanvasItem** that either has no parent, has non-**CanvasItem** parent or it has :ref:`top_level` enabled. @@ -1310,7 +1358,7 @@ Returns the global transform matrix of this item, i.e. the combined transform up .. rst-class:: classref-method -:ref:`Transform2D` **get_global_transform_with_canvas**\ (\ ) |const| +:ref:`Transform2D` **get_global_transform_with_canvas**\ (\ ) |const| :ref:`🔗` Returns the transform from the local coordinate system of this **CanvasItem** to the :ref:`Viewport`\ s coordinate system. @@ -1318,11 +1366,23 @@ Returns the transform from the local coordinate system of this **CanvasItem** to ---- +.. _class_CanvasItem_method_get_instance_shader_parameter: + +.. rst-class:: classref-method + +:ref:`Variant` **get_instance_shader_parameter**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Get the value of a shader parameter as set on this instance. + +.. rst-class:: classref-item-separator + +---- + .. _class_CanvasItem_method_get_local_mouse_position: .. rst-class:: classref-method -:ref:`Vector2` **get_local_mouse_position**\ (\ ) |const| +:ref:`Vector2` **get_local_mouse_position**\ (\ ) |const| :ref:`🔗` Returns the mouse's position in this **CanvasItem** using the local coordinate system of this **CanvasItem**. @@ -1334,11 +1394,11 @@ Returns the mouse's position in this **CanvasItem** using the local coordinate s .. rst-class:: classref-method -:ref:`Transform2D` **get_screen_transform**\ (\ ) |const| +:ref:`Transform2D` **get_screen_transform**\ (\ ) |const| :ref:`🔗` Returns the transform of this **CanvasItem** in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins. -Equals to :ref:`get_global_transform` if the window is embedded (see :ref:`Viewport.gui_embed_subwindows`). +Equals to :ref:`get_global_transform()` if the window is embedded (see :ref:`Viewport.gui_embed_subwindows`). .. rst-class:: classref-item-separator @@ -1348,9 +1408,9 @@ Equals to :ref:`get_global_transform` **get_transform**\ (\ ) |const| +:ref:`Transform2D` **get_transform**\ (\ ) |const| :ref:`🔗` -Returns the transform matrix of this item. +Returns the transform matrix of this **CanvasItem**. .. rst-class:: classref-item-separator @@ -1360,9 +1420,9 @@ Returns the transform matrix of this item. .. rst-class:: classref-method -:ref:`Rect2` **get_viewport_rect**\ (\ ) |const| +:ref:`Rect2` **get_viewport_rect**\ (\ ) |const| :ref:`🔗` -Returns the viewport's boundaries as a :ref:`Rect2`. +Returns this node's viewport boundaries as a :ref:`Rect2`. See also :ref:`Node.get_viewport()`. .. rst-class:: classref-item-separator @@ -1372,9 +1432,9 @@ Returns the viewport's boundaries as a :ref:`Rect2`. .. rst-class:: classref-method -:ref:`Transform2D` **get_viewport_transform**\ (\ ) |const| +:ref:`Transform2D` **get_viewport_transform**\ (\ ) |const| :ref:`🔗` -Returns the transform from the coordinate system of the canvas, this item is in, to the :ref:`Viewport`\ s embedders coordinate system. +Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport embedder's coordinate system. See also :ref:`Viewport.get_final_transform()` and :ref:`Node.get_viewport()`. .. rst-class:: classref-item-separator @@ -1384,9 +1444,9 @@ Returns the transform from the coordinate system of the canvas, this item is in, .. rst-class:: classref-method -:ref:`bool` **get_visibility_layer_bit**\ (\ layer\: :ref:`int`\ ) |const| +:ref:`bool` **get_visibility_layer_bit**\ (\ layer\: :ref:`int`\ ) |const| :ref:`🔗` -Returns an individual bit on the rendering visibility layer. +Returns ``true`` if the layer at the given index is set in :ref:`visibility_layer`. .. rst-class:: classref-item-separator @@ -1396,9 +1456,11 @@ Returns an individual bit on the rendering visibility layer. .. rst-class:: classref-method -:ref:`World2D` **get_world_2d**\ (\ ) |const| +:ref:`World2D` **get_world_2d**\ (\ ) |const| :ref:`🔗` + +Returns the :ref:`World2D` this node is registered to. -Returns the :ref:`World2D` where this item is in. +Usually, this is the same as this node's viewport (see :ref:`Node.get_viewport()` and :ref:`Viewport.find_world_2d()`). .. rst-class:: classref-item-separator @@ -1408,7 +1470,7 @@ Returns the :ref:`World2D` where this item is in. .. rst-class:: classref-method -|void| **hide**\ (\ ) +|void| **hide**\ (\ ) :ref:`🔗` Hide the **CanvasItem** if it's currently visible. This is equivalent to setting :ref:`visible` to ``false``. @@ -1420,9 +1482,9 @@ Hide the **CanvasItem** if it's currently visible. This is equivalent to setting .. rst-class:: classref-method -:ref:`bool` **is_local_transform_notification_enabled**\ (\ ) |const| +:ref:`bool` **is_local_transform_notification_enabled**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if local transform notifications are communicated to children. +Returns ``true`` if the node receives :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED` whenever its local transform changes. This is enabled with :ref:`set_notify_local_transform()`. .. rst-class:: classref-item-separator @@ -1432,9 +1494,9 @@ Returns ``true`` if local transform notifications are communicated to children. .. rst-class:: classref-method -:ref:`bool` **is_transform_notification_enabled**\ (\ ) |const| +:ref:`bool` **is_transform_notification_enabled**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if global transform notifications are communicated to children. +Returns ``true`` if the node receives :ref:`NOTIFICATION_TRANSFORM_CHANGED` whenever its global transform changes. This is enabled with :ref:`set_notify_transform()`. .. rst-class:: classref-item-separator @@ -1444,9 +1506,13 @@ Returns ``true`` if global transform notifications are communicated to children. .. rst-class:: classref-method -:ref:`bool` **is_visible_in_tree**\ (\ ) |const| +:ref:`bool` **is_visible_in_tree**\ (\ ) |const| :ref:`🔗` + +Returns ``true`` if the node is present in the :ref:`SceneTree`, its :ref:`visible` property is ``true`` and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see :ref:`_draw()`). -Returns ``true`` if the node is present in the :ref:`SceneTree`, its :ref:`visible` property is ``true`` and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see :ref:`_draw`). +Visibility is checked only in parent nodes that inherit from **CanvasItem**, :ref:`CanvasLayer`, and :ref:`Window`. If the parent is of any other type (such as :ref:`Node`, :ref:`AnimationPlayer`, or :ref:`Node3D`), it is assumed to be visible. + +\ **Note:** This method does not take :ref:`visibility_layer` into account, so even if this method returns ``true``, the node might end up not being rendered. .. rst-class:: classref-item-separator @@ -1456,9 +1522,15 @@ Returns ``true`` if the node is present in the :ref:`SceneTree` .. rst-class:: classref-method -:ref:`Vector2` **make_canvas_position_local**\ (\ screen_point\: :ref:`Vector2`\ ) |const| +:ref:`Vector2` **make_canvas_position_local**\ (\ viewport_point\: :ref:`Vector2`\ ) |const| :ref:`🔗` + +Transforms ``viewport_point`` from the viewport's coordinates to this node's local coordinates. -Assigns ``screen_point`` as this node's new local transform. +For the opposite operation, use :ref:`get_global_transform_with_canvas()`. + +:: + + var viewport_point = get_global_transform_with_canvas() * local_point .. rst-class:: classref-item-separator @@ -1468,9 +1540,9 @@ Assigns ``screen_point`` as this node's new local transform. .. rst-class:: classref-method -:ref:`InputEvent` **make_input_local**\ (\ event\: :ref:`InputEvent`\ ) |const| +:ref:`InputEvent` **make_input_local**\ (\ event\: :ref:`InputEvent`\ ) |const| :ref:`🔗` -Transformations issued by ``event``'s inputs are applied in local space instead of global space. +Returns a copy of the given ``event`` with its coordinates converted from global space to this **CanvasItem**'s local space. If not possible, returns the same :ref:`InputEvent` unchanged. .. rst-class:: classref-item-separator @@ -1480,11 +1552,9 @@ Transformations issued by ``event``'s inputs are applied in local space instead .. rst-class:: classref-method -|void| **move_to_front**\ (\ ) - -Moves this node to display on top of its siblings. +|void| **move_to_front**\ (\ ) :ref:`🔗` -Internally, the node is moved to the bottom of parent's child list. The method has no effect on nodes without a parent. +Moves this node below its siblings, usually causing the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also :ref:`Node.move_child()`. .. rst-class:: classref-item-separator @@ -1494,9 +1564,25 @@ Internally, the node is moved to the bottom of parent's child list. The method h .. rst-class:: classref-method -|void| **queue_redraw**\ (\ ) +|void| **queue_redraw**\ (\ ) :ref:`🔗` + +Queues the **CanvasItem** to redraw. During idle time, if **CanvasItem** is visible, :ref:`NOTIFICATION_DRAW` is sent and :ref:`_draw()` is called. This only occurs **once** per frame, even if this method has been called multiple times. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CanvasItem_method_set_instance_shader_parameter: + +.. rst-class:: classref-method + +|void| **set_instance_shader_parameter**\ (\ name\: :ref:`StringName`, value\: :ref:`Variant`\ ) :ref:`🔗` + +Set the value of a shader uniform for this instance only (`per-instance uniform <../tutorials/shaders/shader_reference/shading_language.html#per-instance-uniforms>`__). See also :ref:`ShaderMaterial.set_shader_parameter()` to assign a uniform on all instances using the same :ref:`ShaderMaterial`. -Queues the **CanvasItem** to redraw. During idle time, if **CanvasItem** is visible, :ref:`NOTIFICATION_DRAW` is sent and :ref:`_draw` is called. This only occurs **once** per frame, even if this method has been called multiple times. +\ **Note:** For a shader uniform to be assignable on a per-instance basis, it *must* be defined with ``instance uniform ...`` rather than ``uniform ...`` in the shader code. + +\ **Note:** ``name`` is case-sensitive and must match the name of the uniform in the code exactly (not the capitalized name in the inspector). .. rst-class:: classref-item-separator @@ -1506,9 +1592,11 @@ Queues the **CanvasItem** to redraw. During idle time, if **CanvasItem** is visi .. rst-class:: classref-method -|void| **set_notify_local_transform**\ (\ enable\: :ref:`bool`\ ) +|void| **set_notify_local_transform**\ (\ enable\: :ref:`bool`\ ) :ref:`🔗` + +If ``true``, the node will receive :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED` whenever its local transform changes. -If ``enable`` is ``true``, this node will receive :ref:`NOTIFICATION_LOCAL_TRANSFORM_CHANGED` when its local transform changes. +\ **Note:** Many canvas items such as :ref:`Bone2D` or :ref:`CollisionShape2D` automatically enable this in order to function correctly. .. rst-class:: classref-item-separator @@ -1518,9 +1606,11 @@ If ``enable`` is ``true``, this node will receive :ref:`NOTIFICATION_LOCAL_TRANS .. rst-class:: classref-method -|void| **set_notify_transform**\ (\ enable\: :ref:`bool`\ ) +|void| **set_notify_transform**\ (\ enable\: :ref:`bool`\ ) :ref:`🔗` -If ``enable`` is ``true``, this node will receive :ref:`NOTIFICATION_TRANSFORM_CHANGED` when its global transform changes. +If ``true``, the node will receive :ref:`NOTIFICATION_TRANSFORM_CHANGED` whenever global transform changes. + +\ **Note:** Many canvas items such as :ref:`Camera2D` or :ref:`Light2D` automatically enable this in order to function correctly. .. rst-class:: classref-item-separator @@ -1530,7 +1620,7 @@ If ``enable`` is ``true``, this node will receive :ref:`NOTIFICATION_TRANSFORM_C .. rst-class:: classref-method -|void| **set_visibility_layer_bit**\ (\ layer\: :ref:`int`, enabled\: :ref:`bool`\ ) +|void| **set_visibility_layer_bit**\ (\ layer\: :ref:`int`, enabled\: :ref:`bool`\ ) :ref:`🔗` Set/clear individual bits on the rendering visibility layer. This simplifies editing this **CanvasItem**'s visibility layer. @@ -1542,11 +1632,14 @@ Set/clear individual bits on the rendering visibility layer. This simplifies edi .. rst-class:: classref-method -|void| **show**\ (\ ) +|void| **show**\ (\ ) :ref:`🔗` + +Show the **CanvasItem** if it's currently hidden. This is equivalent to setting :ref:`visible` to ``true``. -Show the **CanvasItem** if it's currently hidden. This is equivalent to setting :ref:`visible` to ``true``. For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. +\ **Note:** For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_canvasitemmaterial.rst b/classes/class_canvasitemmaterial.rst index eb657b52a74..39d8b0a79bf 100644 --- a/classes/class_canvasitemmaterial.rst +++ b/classes/class_canvasitemmaterial.rst @@ -56,7 +56,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **BlendMode**: +enum **BlendMode**: :ref:`🔗` .. _class_CanvasItemMaterial_constant_BLEND_MODE_MIX: @@ -106,7 +106,7 @@ Mix blending mode. Colors are assumed to be premultiplied by the alpha (opacity) .. rst-class:: classref-enumeration -enum **LightMode**: +enum **LightMode**: :ref:`🔗` .. _class_CanvasItemMaterial_constant_LIGHT_MODE_NORMAL: @@ -145,7 +145,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`BlendMode` **blend_mode** = ``0`` +:ref:`BlendMode` **blend_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -162,7 +162,7 @@ The manner in which a material's rendering is applied to underlying textures. .. rst-class:: classref-property -:ref:`LightMode` **light_mode** = ``0`` +:ref:`LightMode` **light_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -179,7 +179,7 @@ The manner in which material reacts to lighting. .. rst-class:: classref-property -:ref:`int` **particles_anim_h_frames** +:ref:`int` **particles_anim_h_frames** :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,7 +198,7 @@ The number of columns in the spritesheet assigned as :ref:`Texture2D` **particles_anim_loop** +:ref:`bool` **particles_anim_loop** :ref:`🔗` .. rst-class:: classref-property-setget @@ -217,7 +217,7 @@ If ``true``, the particles animation will loop. .. rst-class:: classref-property -:ref:`int` **particles_anim_v_frames** +:ref:`int` **particles_anim_v_frames** :ref:`🔗` .. rst-class:: classref-property-setget @@ -236,7 +236,7 @@ The number of rows in the spritesheet assigned as :ref:`Texture2D` **particles_animation** = ``false`` +:ref:`bool` **particles_animation** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -248,6 +248,7 @@ If ``true``, enable spritesheet-based animation features when assigned to :ref:` This property (and other ``particles_anim_*`` properties that depend on it) has no effect on other types of nodes. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index 792e9d30454..81144a77d62 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -27,7 +27,7 @@ Description \ **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. +\ **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 to create an individual **CanvasLayer** for each :ref:`Viewport` you want it to be drawn on. .. rst-class:: classref-introduction-group @@ -38,7 +38,7 @@ Tutorials - :doc:`Canvas layers <../tutorials/2d/canvas_layers>` -- `2D Dodge The Creeps Demo `__ +- `2D Dodge The Creeps Demo `__ .. rst-class:: classref-reftable-group @@ -99,7 +99,7 @@ Signals .. rst-class:: classref-signal -**visibility_changed**\ (\ ) +**visibility_changed**\ (\ ) :ref:`🔗` Emitted when visibility of the layer is changed. See :ref:`visible`. @@ -116,7 +116,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Node` **custom_viewport** +:ref:`Node` **custom_viewport** :ref:`🔗` .. rst-class:: classref-property-setget @@ -133,16 +133,16 @@ The custom :ref:`Viewport` node assigned to the **CanvasLayer**. .. rst-class:: classref-property -:ref:`bool` **follow_viewport_enabled** = ``false`` +:ref:`bool` **follow_viewport_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_follow_viewport**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_following_viewport**\ (\ ) -If enabled, the **CanvasLayer** will use the viewport's transform, so it will move when camera moves instead of being anchored in a fixed position on the screen. +If enabled, the **CanvasLayer** maintains its position in world space. If disabled, the **CanvasLayer** stays in a fixed position on the screen. -Together with :ref:`follow_viewport_scale` it can be used for a pseudo 3D effect. +Together with :ref:`follow_viewport_scale`, this can be used for a pseudo-3D effect. .. rst-class:: classref-item-separator @@ -152,7 +152,7 @@ Together with :ref:`follow_viewport_scale` **follow_viewport_scale** = ``1.0`` +:ref:`float` **follow_viewport_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -169,7 +169,7 @@ Scales the layer when using :ref:`follow_viewport_enabled` **layer** = ``1`` +:ref:`int` **layer** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -180,6 +180,8 @@ Layer index for draw order. Lower values are drawn behind higher values. \ **Note:** If multiple CanvasLayers have the same layer index, :ref:`CanvasItem` children of one CanvasLayer are drawn behind the :ref:`CanvasItem` children of the other CanvasLayer. Which CanvasLayer is drawn in front is non-deterministic. +\ **Note:** The layer index should be between :ref:`RenderingServer.CANVAS_LAYER_MIN` and :ref:`RenderingServer.CANVAS_LAYER_MAX` (inclusive). Any other value will wrap around. + .. rst-class:: classref-item-separator ---- @@ -188,7 +190,7 @@ Layer index for draw order. Lower values are drawn behind higher values. .. rst-class:: classref-property -:ref:`Vector2` **offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -205,7 +207,7 @@ The layer's base offset. .. rst-class:: classref-property -:ref:`float` **rotation** = ``0.0`` +:ref:`float` **rotation** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -222,7 +224,7 @@ The layer's rotation in radians. .. rst-class:: classref-property -:ref:`Vector2` **scale** = ``Vector2(1, 1)`` +:ref:`Vector2` **scale** = ``Vector2(1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -239,7 +241,7 @@ The layer's scale. .. rst-class:: classref-property -:ref:`Transform2D` **transform** = ``Transform2D(1, 0, 0, 1, 0, 0)`` +:ref:`Transform2D` **transform** = ``Transform2D(1, 0, 0, 1, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -256,7 +258,7 @@ The layer's transform. .. rst-class:: classref-property -:ref:`bool` **visible** = ``true`` +:ref:`bool` **visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -280,7 +282,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`RID` **get_canvas**\ (\ ) |const| +:ref:`RID` **get_canvas**\ (\ ) |const| :ref:`🔗` Returns the RID of the canvas used by this layer. @@ -292,7 +294,7 @@ Returns the RID of the canvas used by this layer. .. rst-class:: classref-method -:ref:`Transform2D` **get_final_transform**\ (\ ) |const| +:ref:`Transform2D` **get_final_transform**\ (\ ) |const| :ref:`🔗` Returns the transform from the **CanvasLayer**\ s coordinate system to the :ref:`Viewport`\ s coordinate system. @@ -304,7 +306,7 @@ Returns the transform from the **CanvasLayer**\ s coordinate system to the :ref: .. rst-class:: classref-method -|void| **hide**\ (\ ) +|void| **hide**\ (\ ) :ref:`🔗` Hides any :ref:`CanvasItem` under this **CanvasLayer**. This is equivalent to setting :ref:`visible` to ``false``. @@ -316,11 +318,12 @@ Hides any :ref:`CanvasItem` under this **CanvasLayer**. This i .. rst-class:: classref-method -|void| **show**\ (\ ) +|void| **show**\ (\ ) :ref:`🔗` Shows any :ref:`CanvasItem` under this **CanvasLayer**. This is equivalent to setting :ref:`visible` to ``true``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_canvasmodulate.rst b/classes/class_canvasmodulate.rst index 645746d72f6..56d42164049 100644 --- a/classes/class_canvasmodulate.rst +++ b/classes/class_canvasmodulate.rst @@ -24,6 +24,13 @@ Description **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-introduction-group + +Tutorials +--------- + +- :doc:`2D lights and shadows <../tutorials/2d/2d_lights_and_shadows>` + .. rst-class:: classref-reftable-group Properties @@ -49,7 +56,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -59,6 +66,7 @@ Property Descriptions The tint color to apply. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_canvastexture.rst b/classes/class_canvastexture.rst index 281813669d7..f387c6583ec 100644 --- a/classes/class_canvastexture.rst +++ b/classes/class_canvastexture.rst @@ -69,7 +69,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Texture2D` **diffuse_texture** +:ref:`Texture2D` **diffuse_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -86,7 +86,7 @@ The diffuse (color) texture to use. This is the main texture you want to set in .. rst-class:: classref-property -:ref:`Texture2D` **normal_texture** +:ref:`Texture2D` **normal_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -105,7 +105,7 @@ The normal map texture to use. Only has a visible effect if :ref:`Light2D` **specular_color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **specular_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -122,7 +122,7 @@ The multiplier for specular reflection colors. The :ref:`Light2D` .. rst-class:: classref-property -:ref:`float` **specular_shininess** = ``1.0`` +:ref:`float` **specular_shininess** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -139,7 +139,7 @@ The specular exponent for :ref:`Light2D` specular reflections. Hi .. rst-class:: classref-property -:ref:`Texture2D` **specular_texture** +:ref:`Texture2D` **specular_texture** :ref:`🔗` .. rst-class:: classref-property-setget @@ -156,7 +156,7 @@ The specular map to use for :ref:`Light2D` specular reflections. .. rst-class:: classref-property -:ref:`TextureFilter` **texture_filter** = ``0`` +:ref:`TextureFilter` **texture_filter** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -173,7 +173,7 @@ The texture filtering mode to use when drawing this **CanvasTexture**. .. rst-class:: classref-property -:ref:`TextureRepeat` **texture_repeat** = ``0`` +:ref:`TextureRepeat` **texture_repeat** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -183,6 +183,7 @@ The texture filtering mode to use when drawing this **CanvasTexture**. The texture repeat mode to use when drawing this **CanvasTexture**. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_capsulemesh.rst b/classes/class_capsulemesh.rst index 2cdbd1b4777..0d0078c6c84 100644 --- a/classes/class_capsulemesh.rst +++ b/classes/class_capsulemesh.rst @@ -52,7 +52,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **height** = ``2.0`` +:ref:`float` **height** = ``2.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -61,6 +61,8 @@ Property Descriptions Total height of the capsule mesh (including the hemispherical ends). +\ **Note:** The :ref:`height` of a capsule must be at least twice its :ref:`radius`. Otherwise, the capsule becomes a circle. If the :ref:`height` is less than twice the :ref:`radius`, the properties adjust to a valid value. + .. rst-class:: classref-item-separator ---- @@ -69,7 +71,7 @@ Total height of the capsule mesh (including the hemispherical ends). .. rst-class:: classref-property -:ref:`int` **radial_segments** = ``64`` +:ref:`int` **radial_segments** = ``64`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -86,7 +88,7 @@ Number of radial segments on the capsule mesh. .. rst-class:: classref-property -:ref:`float` **radius** = ``0.5`` +:ref:`float` **radius** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -95,6 +97,8 @@ Number of radial segments on the capsule mesh. Radius of the capsule mesh. +\ **Note:** The :ref:`radius` of a capsule cannot be greater than half of its :ref:`height`. Otherwise, the capsule becomes a circle. If the :ref:`radius` is greater than half of the :ref:`height`, the properties adjust to a valid value. + .. rst-class:: classref-item-separator ---- @@ -103,7 +107,7 @@ Radius of the capsule mesh. .. rst-class:: classref-property -:ref:`int` **rings** = ``8`` +:ref:`int` **rings** = ``8`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -113,6 +117,7 @@ Radius of the capsule mesh. Number of rings along the height of the capsule. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_capsuleshape2d.rst b/classes/class_capsuleshape2d.rst index d2d002d1079..a28e551347e 100644 --- a/classes/class_capsuleshape2d.rst +++ b/classes/class_capsuleshape2d.rst @@ -31,11 +31,13 @@ Properties .. table:: :widths: auto - +---------------------------+-----------------------------------------------------+----------+ - | :ref:`float` | :ref:`height` | ``30.0`` | - +---------------------------+-----------------------------------------------------+----------+ - | :ref:`float` | :ref:`radius` | ``10.0`` | - +---------------------------+-----------------------------------------------------+----------+ + +---------------------------+-------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`height` | ``30.0`` | + +---------------------------+-------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`mid_height` | | + +---------------------------+-------------------------------------------------------------+----------+ + | :ref:`float` | :ref:`radius` | ``10.0`` | + +---------------------------+-------------------------------------------------------------+----------+ .. rst-class:: classref-section-separator @@ -50,14 +52,33 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **height** = ``30.0`` +:ref:`float` **height** = ``30.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_height**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_height**\ (\ ) -The capsule's height. +The capsule's full height, including the semicircles. + +\ **Note:** The :ref:`height` of a capsule must be at least twice its :ref:`radius`. Otherwise, the capsule becomes a circle. If the :ref:`height` is less than twice the :ref:`radius`, the properties adjust to a valid value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CapsuleShape2D_property_mid_height: + +.. rst-class:: classref-property + +:ref:`float` **mid_height** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mid_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_mid_height**\ (\ ) + +The capsule's height, excluding the semicircles. This is the height of the central rectangular part in the middle of the capsule, and is the distance between the centers of the two semicircles. This is a wrapper for :ref:`height`. .. rst-class:: classref-item-separator @@ -67,7 +88,7 @@ The capsule's height. .. rst-class:: classref-property -:ref:`float` **radius** = ``10.0`` +:ref:`float` **radius** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -76,7 +97,10 @@ The capsule's height. The capsule's radius. +\ **Note:** The :ref:`radius` of a capsule cannot be greater than half of its :ref:`height`. Otherwise, the capsule becomes a circle. If the :ref:`radius` is greater than half of the :ref:`height`, the properties adjust to a valid value. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_capsuleshape3d.rst b/classes/class_capsuleshape3d.rst index 0bde8e5d166..c651da28a0d 100644 --- a/classes/class_capsuleshape3d.rst +++ b/classes/class_capsuleshape3d.rst @@ -28,7 +28,7 @@ A 3D capsule shape, intended for use in physics. Usually used to provide a shape Tutorials --------- -- `3D Physics Tests Demo `__ +- `3D Physics Tests Demo `__ .. rst-class:: classref-reftable-group @@ -38,11 +38,13 @@ Properties .. table:: :widths: auto - +---------------------------+-----------------------------------------------------+---------+ - | :ref:`float` | :ref:`height` | ``2.0`` | - +---------------------------+-----------------------------------------------------+---------+ - | :ref:`float` | :ref:`radius` | ``0.5`` | - +---------------------------+-----------------------------------------------------+---------+ + +---------------------------+-------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`height` | ``2.0`` | + +---------------------------+-------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`mid_height` | | + +---------------------------+-------------------------------------------------------------+---------+ + | :ref:`float` | :ref:`radius` | ``0.5`` | + +---------------------------+-------------------------------------------------------------+---------+ .. rst-class:: classref-section-separator @@ -57,14 +59,33 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **height** = ``2.0`` +:ref:`float` **height** = ``2.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_height**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_height**\ (\ ) -The capsule's height. +The capsule's full height, including the hemispheres. + +\ **Note:** The :ref:`height` of a capsule must be at least twice its :ref:`radius`. Otherwise, the capsule becomes a sphere. If the :ref:`height` is less than twice the :ref:`radius`, the properties adjust to a valid value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CapsuleShape3D_property_mid_height: + +.. rst-class:: classref-property + +:ref:`float` **mid_height** :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mid_height**\ (\ value\: :ref:`float`\ ) +- :ref:`float` **get_mid_height**\ (\ ) + +The capsule's height, excluding the hemispheres. This is the height of the central cylindrical part in the middle of the capsule, and is the distance between the centers of the two hemispheres. This is a wrapper for :ref:`height`. .. rst-class:: classref-item-separator @@ -74,7 +95,7 @@ The capsule's height. .. rst-class:: classref-property -:ref:`float` **radius** = ``0.5`` +:ref:`float` **radius** = ``0.5`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -83,7 +104,10 @@ The capsule's height. The capsule's radius. +\ **Note:** The :ref:`radius` of a capsule cannot be greater than half of its :ref:`height`. Otherwise, the capsule becomes a sphere. If the :ref:`radius` is greater than half of the :ref:`height`, the properties adjust to a valid value. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_centercontainer.rst b/classes/class_centercontainer.rst index 65262727954..a4139a5ef6c 100644 --- a/classes/class_centercontainer.rst +++ b/classes/class_centercontainer.rst @@ -53,7 +53,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **use_top_left** = ``false`` +:ref:`bool` **use_top_left** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -63,6 +63,7 @@ Property Descriptions If ``true``, centers children relative to the **CenterContainer**'s top left corner. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_characterbody2d.rst b/classes/class_characterbody2d.rst index b18d5619598..659ba422d1b 100644 --- a/classes/class_characterbody2d.rst +++ b/classes/class_characterbody2d.rst @@ -19,7 +19,7 @@ A 2D physics body specialized for characters moved by script. Description ----------- -**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. +**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. For game objects that don't require complex movement or collision detection, such as moving platforms, :ref:`AnimatableBody2D` is simpler to configure. @@ -28,13 +28,17 @@ For game objects that don't require complex movement or collision detection, suc Tutorials --------- +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + - :doc:`Kinematic character (2D) <../tutorials/physics/kinematic_character_2d>` - :doc:`Using CharacterBody2D <../tutorials/physics/using_character_body_2d>` -- `2D Kinematic Character Demo `__ +- `2D Kinematic Character Demo `__ -- `2D Platformer Demo `__ +- `2D Platformer Demo `__ .. rst-class:: classref-reftable-group @@ -49,7 +53,7 @@ Properties +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ | :ref:`bool` | :ref:`floor_constant_speed` | ``false`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ - | :ref:`float` | :ref:`floor_max_angle` | ``0.785398`` | + | :ref:`float` | :ref:`floor_max_angle` | ``0.7853982`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ | :ref:`float` | :ref:`floor_snap_length` | ``1.0`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ @@ -73,7 +77,7 @@ Properties +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ | :ref:`Vector2` | :ref:`velocity` | ``Vector2(0, 0)`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ - | :ref:`float` | :ref:`wall_min_slide_angle` | ``0.261799`` | + | :ref:`float` | :ref:`wall_min_slide_angle` | ``0.2617994`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+--------------------+ .. rst-class:: classref-reftable-group @@ -135,7 +139,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **MotionMode**: +enum **MotionMode**: :ref:`🔗` .. _class_CharacterBody2D_constant_MOTION_MODE_GROUNDED: @@ -161,7 +165,7 @@ Apply when there is no notion of floor or ceiling. All collisions will be report .. rst-class:: classref-enumeration -enum **PlatformOnLeave**: +enum **PlatformOnLeave**: :ref:`🔗` .. _class_CharacterBody2D_constant_PLATFORM_ON_LEAVE_ADD_VELOCITY: @@ -200,7 +204,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **floor_block_on_wall** = ``true`` +:ref:`bool` **floor_block_on_wall** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -217,7 +221,7 @@ If ``true``, the body will be able to move on the floor only. This option avoids .. rst-class:: classref-property -:ref:`bool` **floor_constant_speed** = ``false`` +:ref:`bool` **floor_constant_speed** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -236,14 +240,14 @@ If ``true``, the body will always move at the same speed on the ground no matter .. rst-class:: classref-property -:ref:`float` **floor_max_angle** = ``0.785398`` +:ref:`float` **floor_max_angle** = ``0.7853982`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_floor_max_angle**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_floor_max_angle**\ (\ ) -Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling :ref:`move_and_slide`. The default value equals 45 degrees. +Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling :ref:`move_and_slide()`. The default value equals 45 degrees. .. rst-class:: classref-item-separator @@ -253,16 +257,16 @@ Maximum angle (in radians) where a slope is still considered a floor (or a ceili .. rst-class:: classref-property -:ref:`float` **floor_snap_length** = ``1.0`` +:ref:`float` **floor_snap_length** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_floor_snap_length**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_floor_snap_length**\ (\ ) -Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling :ref:`move_and_slide`. The snapping vector is determined by the given distance along the opposite direction of the :ref:`up_direction`. +Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling :ref:`move_and_slide()`. The snapping vector is determined by the given distance along the opposite direction of the :ref:`up_direction`. -As long as the snapping vector is in contact with the ground and the body moves against :ref:`up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along :ref:`up_direction`, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use :ref:`apply_floor_snap`. +As long as the snapping vector is in contact with the ground and the body moves against :ref:`up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along :ref:`up_direction`, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use :ref:`apply_floor_snap()`. .. rst-class:: classref-item-separator @@ -272,14 +276,14 @@ As long as the snapping vector is in contact with the ground and the body moves .. rst-class:: classref-property -:ref:`bool` **floor_stop_on_slope** = ``true`` +:ref:`bool` **floor_stop_on_slope** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_floor_stop_on_slope_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_floor_stop_on_slope_enabled**\ (\ ) -If ``true``, the body will not slide on slopes when calling :ref:`move_and_slide` when the body is standing still. +If ``true``, the body will not slide on slopes when calling :ref:`move_and_slide()` when the body is standing still. If ``false``, the body will slide on floor's slopes when :ref:`velocity` applies a downward force. @@ -291,14 +295,14 @@ If ``false``, the body will slide on floor's slopes when :ref:`velocity` **max_slides** = ``4`` +:ref:`int` **max_slides** = ``4`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_max_slides**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_max_slides**\ (\ ) -Maximum number of times the body can change direction before it stops when calling :ref:`move_and_slide`. +Maximum number of times the body can change direction before it stops when calling :ref:`move_and_slide()`. Must be greater than zero. .. rst-class:: classref-item-separator @@ -308,14 +312,14 @@ Maximum number of times the body can change direction before it stops when calli .. rst-class:: classref-property -:ref:`MotionMode` **motion_mode** = ``0`` +:ref:`MotionMode` **motion_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_motion_mode**\ (\ value\: :ref:`MotionMode`\ ) - :ref:`MotionMode` **get_motion_mode**\ (\ ) -Sets the motion mode which defines the behavior of :ref:`move_and_slide`. See :ref:`MotionMode` constants for available modes. +Sets the motion mode which defines the behavior of :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -325,7 +329,7 @@ Sets the motion mode which defines the behavior of :ref:`move_and_slide` **platform_floor_layers** = ``4294967295`` +:ref:`int` **platform_floor_layers** = ``4294967295`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -342,14 +346,14 @@ Collision layers that will be included for detecting floor bodies that will act .. rst-class:: classref-property -:ref:`PlatformOnLeave` **platform_on_leave** = ``0`` +:ref:`PlatformOnLeave` **platform_on_leave** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_platform_on_leave**\ (\ value\: :ref:`PlatformOnLeave`\ ) - :ref:`PlatformOnLeave` **get_platform_on_leave**\ (\ ) -Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. See :ref:`PlatformOnLeave` constants for available behavior. +Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. .. rst-class:: classref-item-separator @@ -359,7 +363,7 @@ Sets the behavior to apply when you leave a moving platform. By default, to be p .. rst-class:: classref-property -:ref:`int` **platform_wall_layers** = ``0`` +:ref:`int` **platform_wall_layers** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -376,14 +380,14 @@ Collision layers that will be included for detecting wall bodies that will act a .. rst-class:: classref-property -:ref:`float` **safe_margin** = ``0.08`` +:ref:`float` **safe_margin** = ``0.08`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_safe_margin**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_safe_margin**\ (\ ) -Extra margin used for collision recovery when calling :ref:`move_and_slide`. +Extra margin used for collision recovery when calling :ref:`move_and_slide()`. If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion. @@ -399,7 +403,7 @@ A lower value forces the collision algorithm to use more exact detection, so it .. rst-class:: classref-property -:ref:`bool` **slide_on_ceiling** = ``true`` +:ref:`bool` **slide_on_ceiling** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -416,14 +420,14 @@ If ``true``, during a jump against the ceiling, the body will slide, if ``false` .. rst-class:: classref-property -:ref:`Vector2` **up_direction** = ``Vector2(0, -1)`` +:ref:`Vector2` **up_direction** = ``Vector2(0, -1)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_up_direction**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_up_direction**\ (\ ) -Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling :ref:`move_and_slide`. Defaults to :ref:`Vector2.UP`. As the vector will be normalized it can't be equal to :ref:`Vector2.ZERO`, if you want all collisions to be reported as walls, consider using :ref:`MOTION_MODE_FLOATING` as :ref:`motion_mode`. +Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling :ref:`move_and_slide()`. Defaults to :ref:`Vector2.UP`. As the vector will be normalized it can't be equal to :ref:`Vector2.ZERO`, if you want all collisions to be reported as walls, consider using :ref:`MOTION_MODE_FLOATING` as :ref:`motion_mode`. .. rst-class:: classref-item-separator @@ -433,14 +437,14 @@ Vector pointing upwards, used to determine what is a wall and what is a floor (o .. rst-class:: classref-property -:ref:`Vector2` **velocity** = ``Vector2(0, 0)`` +:ref:`Vector2` **velocity** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_velocity**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_velocity**\ (\ ) -Current velocity vector in pixels per second, used and modified during calls to :ref:`move_and_slide`. +Current velocity vector in pixels per second, used and modified during calls to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -450,14 +454,14 @@ Current velocity vector in pixels per second, used and modified during calls to .. rst-class:: classref-property -:ref:`float` **wall_min_slide_angle** = ``0.261799`` +:ref:`float` **wall_min_slide_angle** = ``0.2617994`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_wall_min_slide_angle**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_wall_min_slide_angle**\ (\ ) -Minimum angle (in radians) where the body is allowed to slide when it encounters a slope. The default value equals 15 degrees. This property only affects movement when :ref:`motion_mode` is :ref:`MOTION_MODE_FLOATING`. +Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. This property only affects movement when :ref:`motion_mode` is :ref:`MOTION_MODE_FLOATING`. .. rst-class:: classref-section-separator @@ -472,9 +476,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **apply_floor_snap**\ (\ ) +|void| **apply_floor_snap**\ (\ ) :ref:`🔗` -Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when :ref:`is_on_floor` returns ``true``. +Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when :ref:`is_on_floor()` returns ``true``. .. rst-class:: classref-item-separator @@ -484,9 +488,9 @@ Allows to manually apply a snap to the floor regardless of the body's velocity. .. rst-class:: classref-method -:ref:`float` **get_floor_angle**\ (\ up_direction\: :ref:`Vector2` = Vector2(0, -1)\ ) |const| +:ref:`float` **get_floor_angle**\ (\ up_direction\: :ref:`Vector2` = Vector2(0, -1)\ ) |const| :ref:`🔗` -Returns the floor's collision angle at the last collision point according to ``up_direction``, which is :ref:`Vector2.UP` by default. This value is always positive and only valid after calling :ref:`move_and_slide` and when :ref:`is_on_floor` returns ``true``. +Returns the floor's collision angle at the last collision point according to ``up_direction``, which is :ref:`Vector2.UP` by default. This value is always positive and only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. .. rst-class:: classref-item-separator @@ -496,9 +500,11 @@ Returns the floor's collision angle at the last collision point according to ``u .. rst-class:: classref-method -:ref:`Vector2` **get_floor_normal**\ (\ ) |const| +:ref:`Vector2` **get_floor_normal**\ (\ ) |const| :ref:`🔗` -Returns the surface normal of the floor at the last collision point. Only valid after calling :ref:`move_and_slide` and when :ref:`is_on_floor` returns ``true``. +Returns the collision normal of the floor at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. .. rst-class:: classref-item-separator @@ -508,9 +514,9 @@ Returns the surface normal of the floor at the last collision point. Only valid .. rst-class:: classref-method -:ref:`Vector2` **get_last_motion**\ (\ ) |const| +:ref:`Vector2` **get_last_motion**\ (\ ) |const| :ref:`🔗` -Returns the last motion applied to the **CharacterBody2D** during the last call to :ref:`move_and_slide`. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. +Returns the last motion applied to the **CharacterBody2D** during the last call to :ref:`move_and_slide()`. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. .. rst-class:: classref-item-separator @@ -520,9 +526,9 @@ Returns the last motion applied to the **CharacterBody2D** during the last call .. rst-class:: classref-method -:ref:`KinematicCollision2D` **get_last_slide_collision**\ (\ ) +:ref:`KinematicCollision2D` **get_last_slide_collision**\ (\ ) :ref:`🔗` -Returns a :ref:`KinematicCollision2D`, which contains information about the latest collision that occurred during the last call to :ref:`move_and_slide`. +Returns a :ref:`KinematicCollision2D`, which contains information about the latest collision that occurred during the last call to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -532,9 +538,9 @@ Returns a :ref:`KinematicCollision2D`, which contain .. rst-class:: classref-method -:ref:`Vector2` **get_platform_velocity**\ (\ ) |const| +:ref:`Vector2` **get_platform_velocity**\ (\ ) |const| :ref:`🔗` -Returns the linear velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide`. +Returns the linear velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -544,9 +550,9 @@ Returns the linear velocity of the platform at the last collision point. Only va .. rst-class:: classref-method -:ref:`Vector2` **get_position_delta**\ (\ ) |const| +:ref:`Vector2` **get_position_delta**\ (\ ) |const| :ref:`🔗` -Returns the travel (position delta) that occurred during the last call to :ref:`move_and_slide`. +Returns the travel (position delta) that occurred during the last call to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -556,9 +562,9 @@ Returns the travel (position delta) that occurred during the last call to :ref:` .. rst-class:: classref-method -:ref:`Vector2` **get_real_velocity**\ (\ ) |const| +:ref:`Vector2` **get_real_velocity**\ (\ ) |const| :ref:`🔗` -Returns the current real velocity since the last call to :ref:`move_and_slide`. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to :ref:`velocity` which returns the requested velocity. +Returns the current real velocity since the last call to :ref:`move_and_slide()`. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to :ref:`velocity` which returns the requested velocity. .. rst-class:: classref-item-separator @@ -568,11 +574,11 @@ Returns the current real velocity since the last call to :ref:`move_and_slide` **get_slide_collision**\ (\ slide_idx\: :ref:`int`\ ) +:ref:`KinematicCollision2D` **get_slide_collision**\ (\ slide_idx\: :ref:`int`\ ) :ref:`🔗` -Returns a :ref:`KinematicCollision2D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide`. Since the body can collide several times in a single call to :ref:`move_and_slide`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count` - 1). +Returns a :ref:`KinematicCollision2D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide()`. Since the body can collide several times in a single call to :ref:`move_and_slide()`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count()` - 1). -\ **Example usage:**\ +\ **Example:** Iterate through the collisions with a ``for`` loop: .. tabs:: @@ -601,9 +607,9 @@ Returns a :ref:`KinematicCollision2D`, which contain .. rst-class:: classref-method -:ref:`int` **get_slide_collision_count**\ (\ ) |const| +:ref:`int` **get_slide_collision_count**\ (\ ) |const| :ref:`🔗` -Returns the number of times the body collided and changed direction during the last call to :ref:`move_and_slide`. +Returns the number of times the body collided and changed direction during the last call to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -613,9 +619,11 @@ Returns the number of times the body collided and changed direction during the l .. rst-class:: classref-method -:ref:`Vector2` **get_wall_normal**\ (\ ) |const| +:ref:`Vector2` **get_wall_normal**\ (\ ) |const| :ref:`🔗` + +Returns the collision normal of the wall at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_wall()` returns ``true``. -Returns the surface normal of the wall at the last collision point. Only valid after calling :ref:`move_and_slide` and when :ref:`is_on_wall` returns ``true``. +\ **Warning:** The collision normal is not always the same as the surface normal. .. rst-class:: classref-item-separator @@ -625,9 +633,9 @@ Returns the surface normal of the wall at the last collision point. Only valid a .. rst-class:: classref-method -:ref:`bool` **is_on_ceiling**\ (\ ) |const| +:ref:`bool` **is_on_ceiling**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided with the ceiling on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. +Returns ``true`` if the body collided with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. .. rst-class:: classref-item-separator @@ -637,9 +645,9 @@ Returns ``true`` if the body collided with the ceiling on the last call of :ref: .. rst-class:: classref-method -:ref:`bool` **is_on_ceiling_only**\ (\ ) |const| +:ref:`bool` **is_on_ceiling_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided only with the ceiling on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. +Returns ``true`` if the body collided only with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. .. rst-class:: classref-item-separator @@ -649,9 +657,9 @@ Returns ``true`` if the body collided only with the ceiling on the last call of .. rst-class:: classref-method -:ref:`bool` **is_on_floor**\ (\ ) |const| +:ref:`bool` **is_on_floor**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided with the floor on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. +Returns ``true`` if the body collided with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. .. rst-class:: classref-item-separator @@ -661,9 +669,9 @@ Returns ``true`` if the body collided with the floor on the last call of :ref:`m .. rst-class:: classref-method -:ref:`bool` **is_on_floor_only**\ (\ ) |const| +:ref:`bool` **is_on_floor_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided only with the floor on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. +Returns ``true`` if the body collided only with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. .. rst-class:: classref-item-separator @@ -673,9 +681,9 @@ Returns ``true`` if the body collided only with the floor on the last call of :r .. rst-class:: classref-method -:ref:`bool` **is_on_wall**\ (\ ) |const| +:ref:`bool` **is_on_wall**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided with a wall on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. +Returns ``true`` if the body collided with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. .. rst-class:: classref-item-separator @@ -685,9 +693,9 @@ Returns ``true`` if the body collided with a wall on the last call of :ref:`move .. rst-class:: classref-method -:ref:`bool` **is_on_wall_only**\ (\ ) |const| +:ref:`bool` **is_on_wall_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided only with a wall on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. +Returns ``true`` if the body collided only with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. .. rst-class:: classref-item-separator @@ -697,11 +705,11 @@ Returns ``true`` if the body collided only with a wall on the last call of :ref: .. rst-class:: classref-method -:ref:`bool` **move_and_slide**\ (\ ) +:ref:`bool` **move_and_slide**\ (\ ) :ref:`🔗` Moves the body based on :ref:`velocity`. If the body collides with another, it will slide along the other body (by default only on floor) rather than stop immediately. If the other body is a **CharacterBody2D** or :ref:`RigidBody2D`, it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes. -Modifies :ref:`velocity` if a slide collision occurred. To get the latest collision call :ref:`get_last_slide_collision`, for detailed information about collisions that occurred, use :ref:`get_slide_collision`. +Modifies :ref:`velocity` if a slide collision occurred. To get the latest collision call :ref:`get_last_slide_collision()`, for detailed information about collisions that occurred, use :ref:`get_slide_collision()`. When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions. @@ -710,6 +718,7 @@ The general behavior and available properties change according to the :ref:`moti Returns ``true`` if the body collided, otherwise, returns ``false``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_characterbody3d.rst b/classes/class_characterbody3d.rst index d9e49bf051b..1e6fa9f5e82 100644 --- a/classes/class_characterbody3d.rst +++ b/classes/class_characterbody3d.rst @@ -19,7 +19,7 @@ A 3D physics body specialized for characters moved by script. Description ----------- -**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. +**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. For game objects that don't require complex movement or collision detection, such as moving platforms, :ref:`AnimatableBody3D` is simpler to configure. @@ -28,15 +28,19 @@ For game objects that don't require complex movement or collision detection, suc Tutorials --------- +- :doc:`Physics introduction <../tutorials/physics/physics_introduction>` + +- :doc:`Troubleshooting physics issues <../tutorials/physics/troubleshooting_physics_issues>` + - :doc:`Kinematic character (2D) <../tutorials/physics/kinematic_character_2d>` -- `3D Kinematic Character Demo `__ +- `3D Kinematic Character Demo `__ -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `3D Voxel Demo `__ +- `3D Voxel Demo `__ -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -51,7 +55,7 @@ Properties +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ | :ref:`bool` | :ref:`floor_constant_speed` | ``false`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ - | :ref:`float` | :ref:`floor_max_angle` | ``0.785398`` | + | :ref:`float` | :ref:`floor_max_angle` | ``0.7853982`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ | :ref:`float` | :ref:`floor_snap_length` | ``0.1`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ @@ -75,7 +79,7 @@ Properties +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ | :ref:`Vector3` | :ref:`velocity` | ``Vector3(0, 0, 0)`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ - | :ref:`float` | :ref:`wall_min_slide_angle` | ``0.261799`` | + | :ref:`float` | :ref:`wall_min_slide_angle` | ``0.2617994`` | +--------------------------------------------------------------+------------------------------------------------------------------------------------+----------------------+ .. rst-class:: classref-reftable-group @@ -139,7 +143,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **MotionMode**: +enum **MotionMode**: :ref:`🔗` .. _class_CharacterBody3D_constant_MOTION_MODE_GROUNDED: @@ -165,7 +169,7 @@ Apply when there is no notion of floor or ceiling. All collisions will be report .. rst-class:: classref-enumeration -enum **PlatformOnLeave**: +enum **PlatformOnLeave**: :ref:`🔗` .. _class_CharacterBody3D_constant_PLATFORM_ON_LEAVE_ADD_VELOCITY: @@ -204,7 +208,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **floor_block_on_wall** = ``true`` +:ref:`bool` **floor_block_on_wall** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -221,7 +225,7 @@ If ``true``, the body will be able to move on the floor only. This option avoids .. rst-class:: classref-property -:ref:`bool` **floor_constant_speed** = ``false`` +:ref:`bool` **floor_constant_speed** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -240,14 +244,14 @@ If ``true``, the body will always move at the same speed on the ground no matter .. rst-class:: classref-property -:ref:`float` **floor_max_angle** = ``0.785398`` +:ref:`float` **floor_max_angle** = ``0.7853982`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_floor_max_angle**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_floor_max_angle**\ (\ ) -Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling :ref:`move_and_slide`. The default value equals 45 degrees. +Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling :ref:`move_and_slide()`. The default value equals 45 degrees. .. rst-class:: classref-item-separator @@ -257,16 +261,16 @@ Maximum angle (in radians) where a slope is still considered a floor (or a ceili .. rst-class:: classref-property -:ref:`float` **floor_snap_length** = ``0.1`` +:ref:`float` **floor_snap_length** = ``0.1`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_floor_snap_length**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_floor_snap_length**\ (\ ) -Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling :ref:`move_and_slide`. The snapping vector is determined by the given distance along the opposite direction of the :ref:`up_direction`. +Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling :ref:`move_and_slide()`. The snapping vector is determined by the given distance along the opposite direction of the :ref:`up_direction`. -As long as the snapping vector is in contact with the ground and the body moves against :ref:`up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along :ref:`up_direction`, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use :ref:`apply_floor_snap`. +As long as the snapping vector is in contact with the ground and the body moves against :ref:`up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along :ref:`up_direction`, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use :ref:`apply_floor_snap()`. .. rst-class:: classref-item-separator @@ -276,14 +280,14 @@ As long as the snapping vector is in contact with the ground and the body moves .. rst-class:: classref-property -:ref:`bool` **floor_stop_on_slope** = ``true`` +:ref:`bool` **floor_stop_on_slope** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_floor_stop_on_slope_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_floor_stop_on_slope_enabled**\ (\ ) -If ``true``, the body will not slide on slopes when calling :ref:`move_and_slide` when the body is standing still. +If ``true``, the body will not slide on slopes when calling :ref:`move_and_slide()` when the body is standing still. If ``false``, the body will slide on floor's slopes when :ref:`velocity` applies a downward force. @@ -295,14 +299,14 @@ If ``false``, the body will slide on floor's slopes when :ref:`velocity` **max_slides** = ``6`` +:ref:`int` **max_slides** = ``6`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_max_slides**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_max_slides**\ (\ ) -Maximum number of times the body can change direction before it stops when calling :ref:`move_and_slide`. +Maximum number of times the body can change direction before it stops when calling :ref:`move_and_slide()`. Must be greater than zero. .. rst-class:: classref-item-separator @@ -312,14 +316,14 @@ Maximum number of times the body can change direction before it stops when calli .. rst-class:: classref-property -:ref:`MotionMode` **motion_mode** = ``0`` +:ref:`MotionMode` **motion_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_motion_mode**\ (\ value\: :ref:`MotionMode`\ ) - :ref:`MotionMode` **get_motion_mode**\ (\ ) -Sets the motion mode which defines the behavior of :ref:`move_and_slide`. See :ref:`MotionMode` constants for available modes. +Sets the motion mode which defines the behavior of :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -329,7 +333,7 @@ Sets the motion mode which defines the behavior of :ref:`move_and_slide` **platform_floor_layers** = ``4294967295`` +:ref:`int` **platform_floor_layers** = ``4294967295`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -346,14 +350,14 @@ Collision layers that will be included for detecting floor bodies that will act .. rst-class:: classref-property -:ref:`PlatformOnLeave` **platform_on_leave** = ``0`` +:ref:`PlatformOnLeave` **platform_on_leave** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_platform_on_leave**\ (\ value\: :ref:`PlatformOnLeave`\ ) - :ref:`PlatformOnLeave` **get_platform_on_leave**\ (\ ) -Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. See :ref:`PlatformOnLeave` constants for available behavior. +Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. .. rst-class:: classref-item-separator @@ -363,7 +367,7 @@ Sets the behavior to apply when you leave a moving platform. By default, to be p .. rst-class:: classref-property -:ref:`int` **platform_wall_layers** = ``0`` +:ref:`int` **platform_wall_layers** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -380,14 +384,14 @@ Collision layers that will be included for detecting wall bodies that will act a .. rst-class:: classref-property -:ref:`float` **safe_margin** = ``0.001`` +:ref:`float` **safe_margin** = ``0.001`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_safe_margin**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_safe_margin**\ (\ ) -Extra margin used for collision recovery when calling :ref:`move_and_slide`. +Extra margin used for collision recovery when calling :ref:`move_and_slide()`. If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion. @@ -403,7 +407,7 @@ A lower value forces the collision algorithm to use more exact detection, so it .. rst-class:: classref-property -:ref:`bool` **slide_on_ceiling** = ``true`` +:ref:`bool` **slide_on_ceiling** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -420,14 +424,14 @@ If ``true``, during a jump against the ceiling, the body will slide, if ``false` .. rst-class:: classref-property -:ref:`Vector3` **up_direction** = ``Vector3(0, 1, 0)`` +:ref:`Vector3` **up_direction** = ``Vector3(0, 1, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_up_direction**\ (\ value\: :ref:`Vector3`\ ) - :ref:`Vector3` **get_up_direction**\ (\ ) -Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling :ref:`move_and_slide`. Defaults to :ref:`Vector3.UP`. As the vector will be normalized it can't be equal to :ref:`Vector3.ZERO`, if you want all collisions to be reported as walls, consider using :ref:`MOTION_MODE_FLOATING` as :ref:`motion_mode`. +Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling :ref:`move_and_slide()`. Defaults to :ref:`Vector3.UP`. As the vector will be normalized it can't be equal to :ref:`Vector3.ZERO`, if you want all collisions to be reported as walls, consider using :ref:`MOTION_MODE_FLOATING` as :ref:`motion_mode`. .. rst-class:: classref-item-separator @@ -437,14 +441,14 @@ Vector pointing upwards, used to determine what is a wall and what is a floor (o .. rst-class:: classref-property -:ref:`Vector3` **velocity** = ``Vector3(0, 0, 0)`` +:ref:`Vector3` **velocity** = ``Vector3(0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_velocity**\ (\ value\: :ref:`Vector3`\ ) - :ref:`Vector3` **get_velocity**\ (\ ) -Current velocity vector (typically meters per second), used and modified during calls to :ref:`move_and_slide`. +Current velocity vector (typically meters per second), used and modified during calls to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -454,14 +458,14 @@ Current velocity vector (typically meters per second), used and modified during .. rst-class:: classref-property -:ref:`float` **wall_min_slide_angle** = ``0.261799`` +:ref:`float` **wall_min_slide_angle** = ``0.2617994`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_wall_min_slide_angle**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_wall_min_slide_angle**\ (\ ) -Minimum angle (in radians) where the body is allowed to slide when it encounters a slope. The default value equals 15 degrees. When :ref:`motion_mode` is :ref:`MOTION_MODE_GROUNDED`, it only affects movement if :ref:`floor_block_on_wall` is ``true``. +Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. When :ref:`motion_mode` is :ref:`MOTION_MODE_GROUNDED`, it only affects movement if :ref:`floor_block_on_wall` is ``true``. .. rst-class:: classref-section-separator @@ -476,9 +480,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **apply_floor_snap**\ (\ ) +|void| **apply_floor_snap**\ (\ ) :ref:`🔗` -Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when :ref:`is_on_floor` returns ``true``. +Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when :ref:`is_on_floor()` returns ``true``. .. rst-class:: classref-item-separator @@ -488,9 +492,9 @@ Allows to manually apply a snap to the floor regardless of the body's velocity. .. rst-class:: classref-method -:ref:`float` **get_floor_angle**\ (\ up_direction\: :ref:`Vector3` = Vector3(0, 1, 0)\ ) |const| +:ref:`float` **get_floor_angle**\ (\ up_direction\: :ref:`Vector3` = Vector3(0, 1, 0)\ ) |const| :ref:`🔗` -Returns the floor's collision angle at the last collision point according to ``up_direction``, which is :ref:`Vector3.UP` by default. This value is always positive and only valid after calling :ref:`move_and_slide` and when :ref:`is_on_floor` returns ``true``. +Returns the floor's collision angle at the last collision point according to ``up_direction``, which is :ref:`Vector3.UP` by default. This value is always positive and only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. .. rst-class:: classref-item-separator @@ -500,9 +504,11 @@ Returns the floor's collision angle at the last collision point according to ``u .. rst-class:: classref-method -:ref:`Vector3` **get_floor_normal**\ (\ ) |const| +:ref:`Vector3` **get_floor_normal**\ (\ ) |const| :ref:`🔗` -Returns the surface normal of the floor at the last collision point. Only valid after calling :ref:`move_and_slide` and when :ref:`is_on_floor` returns ``true``. +Returns the collision normal of the floor at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_floor()` returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. .. rst-class:: classref-item-separator @@ -512,9 +518,9 @@ Returns the surface normal of the floor at the last collision point. Only valid .. rst-class:: classref-method -:ref:`Vector3` **get_last_motion**\ (\ ) |const| +:ref:`Vector3` **get_last_motion**\ (\ ) |const| :ref:`🔗` -Returns the last motion applied to the **CharacterBody3D** during the last call to :ref:`move_and_slide`. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. +Returns the last motion applied to the **CharacterBody3D** during the last call to :ref:`move_and_slide()`. The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. .. rst-class:: classref-item-separator @@ -524,9 +530,9 @@ Returns the last motion applied to the **CharacterBody3D** during the last call .. rst-class:: classref-method -:ref:`KinematicCollision3D` **get_last_slide_collision**\ (\ ) +:ref:`KinematicCollision3D` **get_last_slide_collision**\ (\ ) :ref:`🔗` -Returns a :ref:`KinematicCollision3D`, which contains information about the latest collision that occurred during the last call to :ref:`move_and_slide`. +Returns a :ref:`KinematicCollision3D`, which contains information about the latest collision that occurred during the last call to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -536,9 +542,9 @@ Returns a :ref:`KinematicCollision3D`, which contain .. rst-class:: classref-method -:ref:`Vector3` **get_platform_angular_velocity**\ (\ ) |const| +:ref:`Vector3` **get_platform_angular_velocity**\ (\ ) |const| :ref:`🔗` -Returns the angular velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide`. +Returns the angular velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -548,9 +554,9 @@ Returns the angular velocity of the platform at the last collision point. Only v .. rst-class:: classref-method -:ref:`Vector3` **get_platform_velocity**\ (\ ) |const| +:ref:`Vector3` **get_platform_velocity**\ (\ ) |const| :ref:`🔗` -Returns the linear velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide`. +Returns the linear velocity of the platform at the last collision point. Only valid after calling :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -560,9 +566,9 @@ Returns the linear velocity of the platform at the last collision point. Only va .. rst-class:: classref-method -:ref:`Vector3` **get_position_delta**\ (\ ) |const| +:ref:`Vector3` **get_position_delta**\ (\ ) |const| :ref:`🔗` -Returns the travel (position delta) that occurred during the last call to :ref:`move_and_slide`. +Returns the travel (position delta) that occurred during the last call to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -572,9 +578,9 @@ Returns the travel (position delta) that occurred during the last call to :ref:` .. rst-class:: classref-method -:ref:`Vector3` **get_real_velocity**\ (\ ) |const| +:ref:`Vector3` **get_real_velocity**\ (\ ) |const| :ref:`🔗` -Returns the current real velocity since the last call to :ref:`move_and_slide`. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to :ref:`velocity` which returns the requested velocity. +Returns the current real velocity since the last call to :ref:`move_and_slide()`. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to :ref:`velocity` which returns the requested velocity. .. rst-class:: classref-item-separator @@ -584,9 +590,9 @@ Returns the current real velocity since the last call to :ref:`move_and_slide` **get_slide_collision**\ (\ slide_idx\: :ref:`int`\ ) +:ref:`KinematicCollision3D` **get_slide_collision**\ (\ slide_idx\: :ref:`int`\ ) :ref:`🔗` -Returns a :ref:`KinematicCollision3D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide`. Since the body can collide several times in a single call to :ref:`move_and_slide`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count` - 1). +Returns a :ref:`KinematicCollision3D`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide()`. Since the body can collide several times in a single call to :ref:`move_and_slide()`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count()` - 1). .. rst-class:: classref-item-separator @@ -596,9 +602,9 @@ Returns a :ref:`KinematicCollision3D`, which contain .. rst-class:: classref-method -:ref:`int` **get_slide_collision_count**\ (\ ) |const| +:ref:`int` **get_slide_collision_count**\ (\ ) |const| :ref:`🔗` -Returns the number of times the body collided and changed direction during the last call to :ref:`move_and_slide`. +Returns the number of times the body collided and changed direction during the last call to :ref:`move_and_slide()`. .. rst-class:: classref-item-separator @@ -608,9 +614,11 @@ Returns the number of times the body collided and changed direction during the l .. rst-class:: classref-method -:ref:`Vector3` **get_wall_normal**\ (\ ) |const| +:ref:`Vector3` **get_wall_normal**\ (\ ) |const| :ref:`🔗` + +Returns the collision normal of the wall at the last collision point. Only valid after calling :ref:`move_and_slide()` and when :ref:`is_on_wall()` returns ``true``. -Returns the surface normal of the wall at the last collision point. Only valid after calling :ref:`move_and_slide` and when :ref:`is_on_wall` returns ``true``. +\ **Warning:** The collision normal is not always the same as the surface normal. .. rst-class:: classref-item-separator @@ -620,9 +628,9 @@ Returns the surface normal of the wall at the last collision point. Only valid a .. rst-class:: classref-method -:ref:`bool` **is_on_ceiling**\ (\ ) |const| +:ref:`bool` **is_on_ceiling**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided with the ceiling on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. +Returns ``true`` if the body collided with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. .. rst-class:: classref-item-separator @@ -632,9 +640,9 @@ Returns ``true`` if the body collided with the ceiling on the last call of :ref: .. rst-class:: classref-method -:ref:`bool` **is_on_ceiling_only**\ (\ ) |const| +:ref:`bool` **is_on_ceiling_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided only with the ceiling on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. +Returns ``true`` if the body collided only with the ceiling on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "ceiling" or not. .. rst-class:: classref-item-separator @@ -644,9 +652,9 @@ Returns ``true`` if the body collided only with the ceiling on the last call of .. rst-class:: classref-method -:ref:`bool` **is_on_floor**\ (\ ) |const| +:ref:`bool` **is_on_floor**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided with the floor on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. +Returns ``true`` if the body collided with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. .. rst-class:: classref-item-separator @@ -656,9 +664,9 @@ Returns ``true`` if the body collided with the floor on the last call of :ref:`m .. rst-class:: classref-method -:ref:`bool` **is_on_floor_only**\ (\ ) |const| +:ref:`bool` **is_on_floor_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided only with the floor on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. +Returns ``true`` if the body collided only with the floor on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "floor" or not. .. rst-class:: classref-item-separator @@ -668,9 +676,9 @@ Returns ``true`` if the body collided only with the floor on the last call of :r .. rst-class:: classref-method -:ref:`bool` **is_on_wall**\ (\ ) |const| +:ref:`bool` **is_on_wall**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided with a wall on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. +Returns ``true`` if the body collided with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. .. rst-class:: classref-item-separator @@ -680,9 +688,9 @@ Returns ``true`` if the body collided with a wall on the last call of :ref:`move .. rst-class:: classref-method -:ref:`bool` **is_on_wall_only**\ (\ ) |const| +:ref:`bool` **is_on_wall_only**\ (\ ) |const| :ref:`🔗` -Returns ``true`` if the body collided only with a wall on the last call of :ref:`move_and_slide`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. +Returns ``true`` if the body collided only with a wall on the last call of :ref:`move_and_slide()`. Otherwise, returns ``false``. The :ref:`up_direction` and :ref:`floor_max_angle` are used to determine whether a surface is "wall" or not. .. rst-class:: classref-item-separator @@ -692,17 +700,18 @@ Returns ``true`` if the body collided only with a wall on the last call of :ref: .. rst-class:: classref-method -:ref:`bool` **move_and_slide**\ (\ ) +:ref:`bool` **move_and_slide**\ (\ ) :ref:`🔗` Moves the body based on :ref:`velocity`. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a **CharacterBody3D** or :ref:`RigidBody3D`, it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes. -Modifies :ref:`velocity` if a slide collision occurred. To get the latest collision call :ref:`get_last_slide_collision`, for more detailed information about collisions that occurred, use :ref:`get_slide_collision`. +Modifies :ref:`velocity` if a slide collision occurred. To get the latest collision call :ref:`get_last_slide_collision()`, for more detailed information about collisions that occurred, use :ref:`get_slide_collision()`. When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions. Returns ``true`` if the body collided, otherwise, returns ``false``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_charfxtransform.rst b/classes/class_charfxtransform.rst index 72f6f398acf..90c31ea4d8b 100644 --- a/classes/class_charfxtransform.rst +++ b/classes/class_charfxtransform.rst @@ -28,8 +28,6 @@ Tutorials - :doc:`BBCode in RichTextLabel <../tutorials/ui/bbcode_in_richtextlabel>` -- `RichTextEffect test project (third-party) `__ - .. rst-class:: classref-reftable-group Properties @@ -79,7 +77,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Color` **color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -96,7 +94,7 @@ The color the character will be drawn with. .. rst-class:: classref-property -:ref:`float` **elapsed_time** = ``0.0`` +:ref:`float` **elapsed_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -115,7 +113,7 @@ The time elapsed since the :ref:`RichTextLabel` was added t .. rst-class:: classref-property -:ref:`Dictionary` **env** = ``{}`` +:ref:`Dictionary` **env** = ``{}`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -138,14 +136,16 @@ For example, the opening BBCode tag ``[example foo=hello bar=true baz=42 color=# .. rst-class:: classref-property -:ref:`RID` **font** = ``RID()`` +:ref:`RID` **font** = ``RID()`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_font**\ (\ value\: :ref:`RID`\ ) - :ref:`RID` **get_font**\ (\ ) -Font resource used to render glyph. +:ref:`TextServer` RID of the font used to render glyph, this value can be used with ``TextServer.font_*`` methods to retrieve font information. + +\ **Note:** Read-only. Setting this property won't affect drawing. .. rst-class:: classref-item-separator @@ -155,14 +155,16 @@ Font resource used to render glyph. .. rst-class:: classref-property -:ref:`int` **glyph_count** = ``0`` +:ref:`int` **glyph_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_glyph_count**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_glyph_count**\ (\ ) -Number of glyphs in the grapheme cluster. This value is set in the first glyph of a cluster. Setting this property won't affect drawing. +Number of glyphs in the grapheme cluster. This value is set in the first glyph of a cluster. + +\ **Note:** Read-only. Setting this property won't affect drawing. .. rst-class:: classref-item-separator @@ -172,14 +174,16 @@ Number of glyphs in the grapheme cluster. This value is set in the first glyph o .. rst-class:: classref-property -:ref:`int` **glyph_flags** = ``0`` +:ref:`int` **glyph_flags** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_glyph_flags**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_glyph_flags**\ (\ ) -Glyph flags. See :ref:`GraphemeFlag` for more info. Setting this property won't affect drawing. +Glyph flags. See :ref:`GraphemeFlag` for more info. + +\ **Note:** Read-only. Setting this property won't affect drawing. .. rst-class:: classref-item-separator @@ -189,14 +193,14 @@ Glyph flags. See :ref:`GraphemeFlag` for more info .. rst-class:: classref-property -:ref:`int` **glyph_index** = ``0`` +:ref:`int` **glyph_index** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_glyph_index**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_glyph_index**\ (\ ) -Font specific glyph index. +Glyph index specific to the :ref:`font`. If you want to replace this glyph, use :ref:`TextServer.font_get_glyph_index()` with :ref:`font` to get a new glyph index for a single character. .. rst-class:: classref-item-separator @@ -206,7 +210,7 @@ Font specific glyph index. .. rst-class:: classref-property -:ref:`Vector2` **offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -223,14 +227,16 @@ The position offset the character will be drawn with (in pixels). .. rst-class:: classref-property -:ref:`bool` **outline** = ``false`` +:ref:`bool` **outline** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_outline**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_outline**\ (\ ) -If ``true``, FX transform is called for outline drawing. Setting this property won't affect drawing. +If ``true``, FX transform is called for outline drawing. + +\ **Note:** Read-only. Setting this property won't affect drawing. .. rst-class:: classref-item-separator @@ -240,14 +246,16 @@ If ``true``, FX transform is called for outline drawing. Setting this property w .. rst-class:: classref-property -:ref:`Vector2i` **range** = ``Vector2i(0, 0)`` +:ref:`Vector2i` **range** = ``Vector2i(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_range**\ (\ value\: :ref:`Vector2i`\ ) - :ref:`Vector2i` **get_range**\ (\ ) -Absolute character range in the string, corresponding to the glyph. Setting this property won't affect drawing. +Absolute character range in the string, corresponding to the glyph. + +\ **Note:** Read-only. Setting this property won't affect drawing. .. rst-class:: classref-item-separator @@ -257,14 +265,16 @@ Absolute character range in the string, corresponding to the glyph. Setting this .. rst-class:: classref-property -:ref:`int` **relative_index** = ``0`` +:ref:`int` **relative_index** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_relative_index**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_relative_index**\ (\ ) -The character offset of the glyph, relative to the current :ref:`RichTextEffect` custom block. Setting this property won't affect drawing. +The character offset of the glyph, relative to the current :ref:`RichTextEffect` custom block. + +\ **Note:** Read-only. Setting this property won't affect drawing. .. rst-class:: classref-item-separator @@ -274,7 +284,7 @@ The character offset of the glyph, relative to the current :ref:`RichTextEffect< .. rst-class:: classref-property -:ref:`Transform2D` **transform** = ``Transform2D(1, 0, 0, 1, 0, 0)`` +:ref:`Transform2D` **transform** = ``Transform2D(1, 0, 0, 1, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -291,7 +301,7 @@ The current transform of the current glyph. It can be overridden (for example, b .. rst-class:: classref-property -:ref:`bool` **visible** = ``true`` +:ref:`bool` **visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -301,6 +311,7 @@ The current transform of the current glyph. It can be overridden (for example, b If ``true``, the character will be drawn. If ``false``, the character will be hidden. Characters around hidden characters will reflow to take the space of hidden characters. If this is not desired, set their :ref:`color` to ``Color(1, 1, 1, 0)`` instead. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_checkbox.rst b/classes/class_checkbox.rst index 39f6ea010a5..74019676d11 100644 --- a/classes/class_checkbox.rst +++ b/classes/class_checkbox.rst @@ -47,25 +47,29 @@ Theme Properties .. table:: :widths: auto - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`int` | :ref:`check_v_offset` | ``0`` | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`checked` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`checked_disabled` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`radio_checked` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`radio_checked_disabled` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`radio_unchecked` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`radio_unchecked_disabled` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`unchecked` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`unchecked_disabled` | | - +-----------------------------------+-------------------------------------------------------------------------------------+-------+ + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`checkbox_checked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`checkbox_unchecked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`check_v_offset` | ``0`` | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_checked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_checked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_unchecked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`radio_unchecked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled` | | + +-----------------------------------+--------------------------------------------------------------------------------------+-----------------------+ .. rst-class:: classref-section-separator @@ -76,11 +80,35 @@ Theme Properties Theme Property Descriptions --------------------------- +.. _class_CheckBox_theme_color_checkbox_checked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **checkbox_checked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the checked icon when the checkbox is pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckBox_theme_color_checkbox_unchecked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **checkbox_unchecked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the unchecked icon when the checkbox is not pressed. + +.. rst-class:: classref-item-separator + +---- + .. _class_CheckBox_theme_constant_check_v_offset: .. rst-class:: classref-themeproperty -:ref:`int` **check_v_offset** = ``0`` +:ref:`int` **check_v_offset** = ``0`` :ref:`🔗` The vertical offset used when rendering the check icons (in pixels). @@ -92,7 +120,7 @@ The vertical offset used when rendering the check icons (in pixels). .. rst-class:: classref-themeproperty -:ref:`Texture2D` **checked** +:ref:`Texture2D` **checked** :ref:`🔗` The check icon to display when the **CheckBox** is checked. @@ -104,7 +132,7 @@ The check icon to display when the **CheckBox** is checked. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **checked_disabled** +:ref:`Texture2D` **checked_disabled** :ref:`🔗` The check icon to display when the **CheckBox** is checked and is disabled. @@ -116,7 +144,7 @@ The check icon to display when the **CheckBox** is checked and is disabled. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **radio_checked** +:ref:`Texture2D` **radio_checked** :ref:`🔗` The check icon to display when the **CheckBox** is configured as a radio button and is checked. @@ -128,7 +156,7 @@ The check icon to display when the **CheckBox** is configured as a radio button .. rst-class:: classref-themeproperty -:ref:`Texture2D` **radio_checked_disabled** +:ref:`Texture2D` **radio_checked_disabled** :ref:`🔗` The check icon to display when the **CheckBox** is configured as a radio button, is disabled, and is unchecked. @@ -140,7 +168,7 @@ The check icon to display when the **CheckBox** is configured as a radio button, .. rst-class:: classref-themeproperty -:ref:`Texture2D` **radio_unchecked** +:ref:`Texture2D` **radio_unchecked** :ref:`🔗` The check icon to display when the **CheckBox** is configured as a radio button and is unchecked. @@ -152,7 +180,7 @@ The check icon to display when the **CheckBox** is configured as a radio button .. rst-class:: classref-themeproperty -:ref:`Texture2D` **radio_unchecked_disabled** +:ref:`Texture2D` **radio_unchecked_disabled** :ref:`🔗` The check icon to display when the **CheckBox** is configured as a radio button, is disabled, and is unchecked. @@ -164,7 +192,7 @@ The check icon to display when the **CheckBox** is configured as a radio button, .. rst-class:: classref-themeproperty -:ref:`Texture2D` **unchecked** +:ref:`Texture2D` **unchecked** :ref:`🔗` The check icon to display when the **CheckBox** is unchecked. @@ -176,11 +204,12 @@ The check icon to display when the **CheckBox** is unchecked. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **unchecked_disabled** +:ref:`Texture2D` **unchecked_disabled** :ref:`🔗` The check icon to display when the **CheckBox** is unchecked and is disabled. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_checkbutton.rst b/classes/class_checkbutton.rst index fc6901bc1e2..0c4217f088a 100644 --- a/classes/class_checkbutton.rst +++ b/classes/class_checkbutton.rst @@ -1,5 +1,8 @@ :github_url: hide +.. meta:: + :keywords: switch, toggle + .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. @@ -45,25 +48,29 @@ Theme Properties .. table:: :widths: auto - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`int` | :ref:`check_v_offset` | ``0`` | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`checked` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`checked_disabled` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`checked_disabled_mirrored` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`checked_mirrored` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`unchecked` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`unchecked_disabled` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`unchecked_disabled_mirrored` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ - | :ref:`Texture2D` | :ref:`unchecked_mirrored` | | - +-----------------------------------+----------------------------------------------------------------------------------------------+-------+ + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`button_checked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`button_unchecked_color` | ``Color(1, 1, 1, 1)`` | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`int` | :ref:`check_v_offset` | ``0`` | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_disabled_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`checked_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_disabled_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ + | :ref:`Texture2D` | :ref:`unchecked_mirrored` | | + +-----------------------------------+----------------------------------------------------------------------------------------------+-----------------------+ .. rst-class:: classref-section-separator @@ -74,11 +81,35 @@ Theme Properties Theme Property Descriptions --------------------------- +.. _class_CheckButton_theme_color_button_checked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **button_checked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the checked icon when the checkbox is pressed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CheckButton_theme_color_button_unchecked_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **button_unchecked_color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` + +The color of the unchecked icon when the checkbox is not pressed. + +.. rst-class:: classref-item-separator + +---- + .. _class_CheckButton_theme_constant_check_v_offset: .. rst-class:: classref-themeproperty -:ref:`int` **check_v_offset** = ``0`` +:ref:`int` **check_v_offset** = ``0`` :ref:`🔗` The vertical offset used when rendering the toggle icons (in pixels). @@ -90,7 +121,7 @@ The vertical offset used when rendering the toggle icons (in pixels). .. rst-class:: classref-themeproperty -:ref:`Texture2D` **checked** +:ref:`Texture2D` **checked** :ref:`🔗` The icon to display when the **CheckButton** is checked (for left-to-right layouts). @@ -102,7 +133,7 @@ The icon to display when the **CheckButton** is checked (for left-to-right layou .. rst-class:: classref-themeproperty -:ref:`Texture2D` **checked_disabled** +:ref:`Texture2D` **checked_disabled** :ref:`🔗` The icon to display when the **CheckButton** is checked and disabled (for left-to-right layouts). @@ -114,7 +145,7 @@ The icon to display when the **CheckButton** is checked and disabled (for left-t .. rst-class:: classref-themeproperty -:ref:`Texture2D` **checked_disabled_mirrored** +:ref:`Texture2D` **checked_disabled_mirrored** :ref:`🔗` The icon to display when the **CheckButton** is checked and disabled (for right-to-left layouts). @@ -126,7 +157,7 @@ The icon to display when the **CheckButton** is checked and disabled (for right- .. rst-class:: classref-themeproperty -:ref:`Texture2D` **checked_mirrored** +:ref:`Texture2D` **checked_mirrored** :ref:`🔗` The icon to display when the **CheckButton** is checked (for right-to-left layouts). @@ -138,7 +169,7 @@ The icon to display when the **CheckButton** is checked (for right-to-left layou .. rst-class:: classref-themeproperty -:ref:`Texture2D` **unchecked** +:ref:`Texture2D` **unchecked** :ref:`🔗` The icon to display when the **CheckButton** is unchecked (for left-to-right layouts). @@ -150,7 +181,7 @@ The icon to display when the **CheckButton** is unchecked (for left-to-right lay .. rst-class:: classref-themeproperty -:ref:`Texture2D` **unchecked_disabled** +:ref:`Texture2D` **unchecked_disabled** :ref:`🔗` The icon to display when the **CheckButton** is unchecked and disabled (for left-to-right layouts). @@ -162,7 +193,7 @@ The icon to display when the **CheckButton** is unchecked and disabled (for left .. rst-class:: classref-themeproperty -:ref:`Texture2D` **unchecked_disabled_mirrored** +:ref:`Texture2D` **unchecked_disabled_mirrored** :ref:`🔗` The icon to display when the **CheckButton** is unchecked and disabled (for right-to-left layouts). @@ -174,11 +205,12 @@ The icon to display when the **CheckButton** is unchecked and disabled (for righ .. rst-class:: classref-themeproperty -:ref:`Texture2D` **unchecked_mirrored** +:ref:`Texture2D` **unchecked_mirrored** :ref:`🔗` The icon to display when the **CheckButton** is unchecked (for right-to-left layouts). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_circleshape2d.rst b/classes/class_circleshape2d.rst index f239f248dc3..9f329d07357 100644 --- a/classes/class_circleshape2d.rst +++ b/classes/class_circleshape2d.rst @@ -48,7 +48,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **radius** = ``10.0`` +:ref:`float` **radius** = ``10.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -58,6 +58,7 @@ Property Descriptions The circle's radius. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_classdb.rst b/classes/class_classdb.rst index e0e2ebfdf49..d222acbc9de 100644 --- a/classes/class_classdb.rst +++ b/classes/class_classdb.rst @@ -29,53 +29,122 @@ Methods .. table:: :widths: auto - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`can_instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`class_exists`\ (\ class\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`class_get_enum_constants`\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`class_get_enum_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`class_get_integer_constant`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`StringName` | :ref:`class_get_integer_constant_enum`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`class_get_integer_constant_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_method_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`class_get_property`\ (\ object\: :ref:`Object`, property\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_property_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Dictionary` | :ref:`class_get_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_signal_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`class_has_enum`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`class_has_integer_constant`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`class_has_method`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`class_has_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Error` | :ref:`class_set_property`\ (\ object\: :ref:`Object`, property\: :ref:`StringName`, value\: :ref:`Variant`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`get_class_list`\ (\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedStringArray` | :ref:`get_inheriters_from_class`\ (\ class\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`StringName` | :ref:`get_parent_class`\ (\ class\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_class_enabled`\ (\ class\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_parent_class`\ (\ class\: :ref:`StringName`, inherits\: :ref:`StringName`\ ) |const| | - +------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`can_instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_call_static`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, ...\ ) |vararg| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_exists`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`APIType` | :ref:`class_get_api_type`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`class_get_enum_constants`\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`class_get_enum_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`class_get_integer_constant`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_integer_constant_enum`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`class_get_integer_constant_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`class_get_method_argument_count`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_method_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_get_property`\ (\ object\: :ref:`Object`, property\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_get_property_default_value`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_property_getter`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_property_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_property_setter`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Dictionary` | :ref:`class_get_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_signal_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_enum`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_integer_constant`\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_method`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`class_has_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Error` | :ref:`class_set_property`\ (\ object\: :ref:`Object`, property\: :ref:`StringName`, value\: :ref:`Variant`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_class_list`\ (\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_inheriters_from_class`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_parent_class`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_class_enabled`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_class_enum_bitfield`\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_parent_class`\ (\ class\: :ref:`StringName`, inherits\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Enumerations +------------ + +.. _enum_ClassDB_APIType: + +.. rst-class:: classref-enumeration + +enum **APIType**: :ref:`🔗` + +.. _class_ClassDB_constant_API_CORE: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_CORE** = ``0`` + +Native Core class type. + +.. _class_ClassDB_constant_API_EDITOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EDITOR** = ``1`` + +Native Editor class type. + +.. _class_ClassDB_constant_API_EXTENSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EXTENSION** = ``2`` + +GDExtension class type. + +.. _class_ClassDB_constant_API_EDITOR_EXTENSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EDITOR_EXTENSION** = ``3`` + +GDExtension Editor class type. + +.. _class_ClassDB_constant_API_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_NONE** = ``4`` + +Unknown class type. .. rst-class:: classref-section-separator @@ -90,7 +159,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`bool` **can_instantiate**\ (\ class\: :ref:`StringName`\ ) |const| +:ref:`bool` **can_instantiate**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns ``true`` if objects can be instantiated from the specified ``class``, otherwise returns ``false``. @@ -98,11 +167,23 @@ Returns ``true`` if objects can be instantiated from the specified ``class``, ot ---- +.. _class_ClassDB_method_class_call_static: + +.. rst-class:: classref-method + +:ref:`Variant` **class_call_static**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, ...\ ) |vararg| :ref:`🔗` + +Calls a static method on a class. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_exists: .. rst-class:: classref-method -:ref:`bool` **class_exists**\ (\ class\: :ref:`StringName`\ ) |const| +:ref:`bool` **class_exists**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether the specified ``class`` is available or not. @@ -110,11 +191,23 @@ Returns whether the specified ``class`` is available or not. ---- +.. _class_ClassDB_method_class_get_api_type: + +.. rst-class:: classref-method + +:ref:`APIType` **class_get_api_type**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the API type of the specified ``class``. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_enum_constants: .. rst-class:: classref-method -:ref:`PackedStringArray` **class_get_enum_constants**\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`PackedStringArray` **class_get_enum_constants**\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with all the keys in ``enum`` of ``class`` or its ancestry. @@ -126,7 +219,7 @@ Returns an array with all the keys in ``enum`` of ``class`` or its ancestry. .. rst-class:: classref-method -:ref:`PackedStringArray` **class_get_enum_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`PackedStringArray` **class_get_enum_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with all the enums of ``class`` or its ancestry. @@ -138,7 +231,7 @@ Returns an array with all the enums of ``class`` or its ancestry. .. rst-class:: classref-method -:ref:`int` **class_get_integer_constant**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| +:ref:`int` **class_get_integer_constant**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the value of the integer constant ``name`` of ``class`` or its ancestry. Always returns 0 when the constant could not be found. @@ -150,7 +243,7 @@ Returns the value of the integer constant ``name`` of ``class`` or its ancestry. .. rst-class:: classref-method -:ref:`StringName` **class_get_integer_constant_enum**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`StringName` **class_get_integer_constant_enum**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns which enum the integer constant ``name`` of ``class`` or its ancestry belongs to. @@ -162,7 +255,7 @@ Returns which enum the integer constant ``name`` of ``class`` or its ancestry be .. rst-class:: classref-method -:ref:`PackedStringArray` **class_get_integer_constant_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`PackedStringArray` **class_get_integer_constant_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with the names all the integer constants of ``class`` or its ancestry. @@ -170,11 +263,23 @@ Returns an array with the names all the integer constants of ``class`` or its an ---- +.. _class_ClassDB_method_class_get_method_argument_count: + +.. rst-class:: classref-method + +:ref:`int` **class_get_method_argument_count**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns the number of arguments of the method ``method`` of ``class`` or its ancestry if ``no_inheritance`` is ``false``. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_method_list: .. rst-class:: classref-method -:ref:`Array`\[:ref:`Dictionary`\] **class_get_method_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`Array`\[:ref:`Dictionary`\] **class_get_method_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with all the methods of ``class`` or its ancestry if ``no_inheritance`` is ``false``. Every element of the array is a :ref:`Dictionary` with the following keys: ``args``, ``default_args``, ``flags``, ``id``, ``name``, ``return: (class_name, hint, hint_string, name, type, usage)``. @@ -188,7 +293,7 @@ Returns an array with all the methods of ``class`` or its ancestry if ``no_inher .. rst-class:: classref-method -:ref:`Variant` **class_get_property**\ (\ object\: :ref:`Object`, property\: :ref:`StringName`\ ) |const| +:ref:`Variant` **class_get_property**\ (\ object\: :ref:`Object`, property\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the value of ``property`` of ``object`` or its ancestry. @@ -196,11 +301,35 @@ Returns the value of ``property`` of ``object`` or its ancestry. ---- +.. _class_ClassDB_method_class_get_property_default_value: + +.. rst-class:: classref-method + +:ref:`Variant` **class_get_property_default_value**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) |const| :ref:`🔗` + +Returns the default value of ``property`` of ``class`` or its ancestor classes. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ClassDB_method_class_get_property_getter: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_property_getter**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) :ref:`🔗` + +Returns the getter method name of ``property`` of ``class``. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_property_list: .. rst-class:: classref-method -:ref:`Array`\[:ref:`Dictionary`\] **class_get_property_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`Array`\[:ref:`Dictionary`\] **class_get_property_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns an array with all the properties of ``class`` or its ancestry if ``no_inheritance`` is ``false``. @@ -208,11 +337,23 @@ Returns an array with all the properties of ``class`` or its ancestry if ``no_in ---- +.. _class_ClassDB_method_class_get_property_setter: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_property_setter**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) :ref:`🔗` + +Returns the setter method name of ``property`` of ``class``. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_signal: .. rst-class:: classref-method -:ref:`Dictionary` **class_get_signal**\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| +:ref:`Dictionary` **class_get_signal**\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the ``signal`` data of ``class`` or its ancestry. The returned value is a :ref:`Dictionary` with the following keys: ``args``, ``default_args``, ``flags``, ``id``, ``name``, ``return: (class_name, hint, hint_string, name, type, usage)``. @@ -224,9 +365,9 @@ Returns the ``signal`` data of ``class`` or its ancestry. The returned value is .. rst-class:: classref-method -:ref:`Array`\[:ref:`Dictionary`\] **class_get_signal_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`Array`\[:ref:`Dictionary`\] **class_get_signal_list**\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` -Returns an array with all the signals of ``class`` or its ancestry if ``no_inheritance`` is ``false``. Every element of the array is a :ref:`Dictionary` as described in :ref:`class_get_signal`. +Returns an array with all the signals of ``class`` or its ancestry if ``no_inheritance`` is ``false``. Every element of the array is a :ref:`Dictionary` as described in :ref:`class_get_signal()`. .. rst-class:: classref-item-separator @@ -236,7 +377,7 @@ Returns an array with all the signals of ``class`` or its ancestry if ``no_inher .. rst-class:: classref-method -:ref:`bool` **class_has_enum**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`bool` **class_has_enum**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns whether ``class`` or its ancestry has an enum called ``name`` or not. @@ -248,7 +389,7 @@ Returns whether ``class`` or its ancestry has an enum called ``name`` or not. .. rst-class:: classref-method -:ref:`bool` **class_has_integer_constant**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| +:ref:`bool` **class_has_integer_constant**\ (\ class\: :ref:`StringName`, name\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether ``class`` or its ancestry has an integer constant called ``name`` or not. @@ -260,7 +401,7 @@ Returns whether ``class`` or its ancestry has an integer constant called ``name` .. rst-class:: classref-method -:ref:`bool` **class_has_method**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| +:ref:`bool` **class_has_method**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` Returns whether ``class`` (or its ancestry if ``no_inheritance`` is ``false``) has a method called ``method`` or not. @@ -272,7 +413,7 @@ Returns whether ``class`` (or its ancestry if ``no_inheritance`` is ``false``) h .. rst-class:: classref-method -:ref:`bool` **class_has_signal**\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| +:ref:`bool` **class_has_signal**\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether ``class`` or its ancestry has a signal called ``signal`` or not. @@ -284,7 +425,7 @@ Returns whether ``class`` or its ancestry has a signal called ``signal`` or not. .. rst-class:: classref-method -:ref:`Error` **class_set_property**\ (\ object\: :ref:`Object`, property\: :ref:`StringName`, value\: :ref:`Variant`\ ) |const| +:ref:`Error` **class_set_property**\ (\ object\: :ref:`Object`, property\: :ref:`StringName`, value\: :ref:`Variant`\ ) |const| :ref:`🔗` Sets ``property`` value of ``object`` to ``value``. @@ -296,7 +437,7 @@ Sets ``property`` value of ``object`` to ``value``. .. rst-class:: classref-method -:ref:`PackedStringArray` **get_class_list**\ (\ ) |const| +:ref:`PackedStringArray` **get_class_list**\ (\ ) |const| :ref:`🔗` Returns the names of all the classes available. @@ -308,7 +449,7 @@ Returns the names of all the classes available. .. rst-class:: classref-method -:ref:`PackedStringArray` **get_inheriters_from_class**\ (\ class\: :ref:`StringName`\ ) |const| +:ref:`PackedStringArray` **get_inheriters_from_class**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the names of all the classes that directly or indirectly inherit from ``class``. @@ -320,7 +461,7 @@ Returns the names of all the classes that directly or indirectly inherit from `` .. rst-class:: classref-method -:ref:`StringName` **get_parent_class**\ (\ class\: :ref:`StringName`\ ) |const| +:ref:`StringName` **get_parent_class**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns the parent class of ``class``. @@ -332,7 +473,7 @@ Returns the parent class of ``class``. .. rst-class:: classref-method -:ref:`Variant` **instantiate**\ (\ class\: :ref:`StringName`\ ) |const| +:ref:`Variant` **instantiate**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Creates an instance of ``class``. @@ -344,7 +485,7 @@ Creates an instance of ``class``. .. rst-class:: classref-method -:ref:`bool` **is_class_enabled**\ (\ class\: :ref:`StringName`\ ) |const| +:ref:`bool` **is_class_enabled**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether this ``class`` is enabled or not. @@ -352,15 +493,28 @@ Returns whether this ``class`` is enabled or not. ---- +.. _class_ClassDB_method_is_class_enum_bitfield: + +.. rst-class:: classref-method + +:ref:`bool` **is_class_enum_bitfield**\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| :ref:`🔗` + +Returns whether ``class`` (or its ancestor classes if ``no_inheritance`` is ``false``) has an enum called ``enum`` that is a bitfield. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_is_parent_class: .. rst-class:: classref-method -:ref:`bool` **is_parent_class**\ (\ class\: :ref:`StringName`, inherits\: :ref:`StringName`\ ) |const| +:ref:`bool` **is_parent_class**\ (\ class\: :ref:`StringName`, inherits\: :ref:`StringName`\ ) |const| :ref:`🔗` Returns whether ``inherits`` is an ancestor of ``class`` or not. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_codeedit.rst b/classes/class_codeedit.rst index d2c2a9bda27..d100ff934cd 100644 --- a/classes/class_codeedit.rst +++ b/classes/class_codeedit.rst @@ -74,6 +74,8 @@ Properties +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ | :ref:`bool` | :ref:`symbol_lookup_on_click` | ``false`` | +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`symbol_tooltip_on_hover` | ``false`` | + +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ | :ref:`TextDirection` | text_direction | ``1`` (overrides :ref:`TextEdit`) | +----------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+ @@ -120,10 +122,14 @@ Methods +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`create_code_region`\ (\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`delete_lines`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`do_indent`\ (\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`duplicate_lines`\ (\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`duplicate_selection`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`fold_all_lines`\ (\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`fold_line`\ (\ line\: :ref:`int`\ ) | @@ -188,6 +194,10 @@ Methods +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_line_folded`\ (\ line\: :ref:`int`\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_lines_down`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`move_lines_up`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_comment_delimiter`\ (\ start_key\: :ref:`String`\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_string_delimiter`\ (\ start_key\: :ref:`String`\ ) | @@ -212,6 +222,8 @@ Methods +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`toggle_foldable_line`\ (\ line\: :ref:`int`\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`toggle_foldable_lines_at_carets`\ (\ ) | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`unfold_all_lines`\ (\ ) | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`unfold_line`\ (\ line\: :ref:`int`\ ) | @@ -270,6 +282,8 @@ Theme Properties +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ | :ref:`Texture2D` | :ref:`can_fold_code_region` | | +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`completion_color_bg` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ | :ref:`Texture2D` | :ref:`executing_line` | | +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ | :ref:`Texture2D` | :ref:`folded` | | @@ -294,9 +308,9 @@ Signals .. rst-class:: classref-signal -**breakpoint_toggled**\ (\ line\: :ref:`int`\ ) +**breakpoint_toggled**\ (\ line\: :ref:`int`\ ) :ref:`🔗` -Emitted when a breakpoint is added or removed from a line. If the line is moved via backspace a removed is emitted at the old line. +Emitted when a breakpoint is added or removed from a line. If the line is removed via backspace, a signal is emitted at the old line. .. rst-class:: classref-item-separator @@ -306,9 +320,23 @@ Emitted when a breakpoint is added or removed from a line. If the line is moved .. rst-class:: classref-signal -**code_completion_requested**\ (\ ) +**code_completion_requested**\ (\ ) :ref:`🔗` -Emitted when the user requests code completion. +Emitted when the user requests code completion. This signal will not be sent if :ref:`_request_code_completion()` is overridden or :ref:`code_completion_enabled` is ``false``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_signal_symbol_hovered: + +.. rst-class:: classref-signal + +**symbol_hovered**\ (\ symbol\: :ref:`String`, line\: :ref:`int`, column\: :ref:`int`\ ) :ref:`🔗` + +Emitted when the user hovers over a symbol. Unlike :ref:`Control.mouse_entered`, this signal is not emitted immediately, but when the cursor is over the symbol for :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` seconds. + +\ **Note:** :ref:`symbol_tooltip_on_hover` must be ``true`` for this signal to be emitted. .. rst-class:: classref-item-separator @@ -318,7 +346,7 @@ Emitted when the user requests code completion. .. rst-class:: classref-signal -**symbol_lookup**\ (\ symbol\: :ref:`String`, line\: :ref:`int`, column\: :ref:`int`\ ) +**symbol_lookup**\ (\ symbol\: :ref:`String`, line\: :ref:`int`, column\: :ref:`int`\ ) :ref:`🔗` Emitted when the user has clicked on a valid symbol. @@ -330,9 +358,11 @@ Emitted when the user has clicked on a valid symbol. .. rst-class:: classref-signal -**symbol_validate**\ (\ symbol\: :ref:`String`\ ) +**symbol_validate**\ (\ symbol\: :ref:`String`\ ) :ref:`🔗` + +Emitted when the user hovers over a symbol. The symbol should be validated and responded to, by calling :ref:`set_symbol_lookup_word_as_valid()`. -Emitted when the user hovers over a symbol. The symbol should be validated and responded to, by calling :ref:`set_symbol_lookup_word_as_valid`. +\ **Note:** :ref:`symbol_lookup_on_click` must be ``true`` for this signal to be emitted. .. rst-class:: classref-section-separator @@ -347,7 +377,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **CodeCompletionKind**: +enum **CodeCompletionKind**: :ref:`🔗` .. _class_CodeEdit_constant_KIND_CLASS: @@ -437,7 +467,7 @@ Marks the option as unclassified or plain text. .. rst-class:: classref-enumeration -enum **CodeCompletionLocation**: +enum **CodeCompletionLocation**: :ref:`🔗` .. _class_CodeEdit_constant_LOCATION_LOCAL: @@ -484,14 +514,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **auto_brace_completion_enabled** = ``false`` +:ref:`bool` **auto_brace_completion_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_brace_completion_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_auto_brace_completion_enabled**\ (\ ) -Sets whether brace pairs should be autocompleted. +If ``true``, uses :ref:`auto_brace_completion_pairs` to automatically insert the closing brace when the opening brace is inserted by typing or autocompletion. Also automatically removes the closing brace when using backspace on the opening brace. .. rst-class:: classref-item-separator @@ -501,14 +531,14 @@ Sets whether brace pairs should be autocompleted. .. rst-class:: classref-property -:ref:`bool` **auto_brace_completion_highlight_matching** = ``false`` +:ref:`bool` **auto_brace_completion_highlight_matching** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_highlight_matching_braces_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_highlight_matching_braces_enabled**\ (\ ) -Highlight mismatching brace pairs. +If ``true``, highlights brace pairs when the caret is on either one, using :ref:`auto_brace_completion_pairs`. If matching, the pairs will be underlined. If a brace is unmatched, it is colored with :ref:`brace_mismatch_color`. .. rst-class:: classref-item-separator @@ -518,14 +548,14 @@ Highlight mismatching brace pairs. .. rst-class:: classref-property -:ref:`Dictionary` **auto_brace_completion_pairs** = ``{ "\"": "\"", "'": "'", "(": ")", "[": "]", "{": "}" }`` +:ref:`Dictionary` **auto_brace_completion_pairs** = ``{ "\"": "\"", "'": "'", "(": ")", "[": "]", "{": "}" }`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_brace_completion_pairs**\ (\ value\: :ref:`Dictionary`\ ) - :ref:`Dictionary` **get_auto_brace_completion_pairs**\ (\ ) -Sets the brace pairs to be autocompleted. +Sets the brace pairs to be autocompleted. For each entry in the dictionary, the key is the opening brace and the value is the closing brace that matches it. A brace is a :ref:`String` made of symbols. See :ref:`auto_brace_completion_enabled` and :ref:`auto_brace_completion_highlight_matching`. .. rst-class:: classref-item-separator @@ -535,14 +565,14 @@ Sets the brace pairs to be autocompleted. .. rst-class:: classref-property -:ref:`bool` **code_completion_enabled** = ``false`` +:ref:`bool` **code_completion_enabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_code_completion_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_code_completion_enabled**\ (\ ) -Sets whether code completion is allowed. +If ``true``, the :ref:`ProjectSettings.input/ui_text_completion_query` action requests code completion. To handle it, see :ref:`_request_code_completion()` or :ref:`code_completion_requested`. .. rst-class:: classref-item-separator @@ -552,7 +582,7 @@ Sets whether code completion is allowed. .. rst-class:: classref-property -:ref:`Array`\[:ref:`String`\] **code_completion_prefixes** = ``[]`` +:ref:`Array`\[:ref:`String`\] **code_completion_prefixes** = ``[]`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -569,7 +599,7 @@ Sets prefixes that will trigger code completion. .. rst-class:: classref-property -:ref:`Array`\[:ref:`String`\] **delimiter_comments** = ``[]`` +:ref:`Array`\[:ref:`String`\] **delimiter_comments** = ``[]`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -586,7 +616,7 @@ Sets the comment delimiters. All existing comment delimiters will be removed. .. rst-class:: classref-property -:ref:`Array`\[:ref:`String`\] **delimiter_strings** = ``["' '", "\" \""]`` +:ref:`Array`\[:ref:`String`\] **delimiter_strings** = ``["' '", "\" \""]`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -603,14 +633,14 @@ Sets the string delimiters. All existing string delimiters will be removed. .. rst-class:: classref-property -:ref:`bool` **gutters_draw_bookmarks** = ``false`` +:ref:`bool` **gutters_draw_bookmarks** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_draw_bookmarks_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_bookmarks_gutter**\ (\ ) -Sets if bookmarked should be drawn in the gutter. This gutter is shared with breakpoints and executing lines. +If ``true``, bookmarks are drawn in the gutter. This gutter is shared with breakpoints and executing lines. See :ref:`set_line_as_bookmarked()`. .. rst-class:: classref-item-separator @@ -620,14 +650,14 @@ Sets if bookmarked should be drawn in the gutter. This gutter is shared with bre .. rst-class:: classref-property -:ref:`bool` **gutters_draw_breakpoints_gutter** = ``false`` +:ref:`bool` **gutters_draw_breakpoints_gutter** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_draw_breakpoints_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_breakpoints_gutter**\ (\ ) -Sets if breakpoints should be drawn in the gutter. This gutter is shared with bookmarks and executing lines. +If ``true``, breakpoints are drawn in the gutter. This gutter is shared with bookmarks and executing lines. Clicking the gutter will toggle the breakpoint for the line, see :ref:`set_line_as_breakpoint()`. .. rst-class:: classref-item-separator @@ -637,14 +667,14 @@ Sets if breakpoints should be drawn in the gutter. This gutter is shared with bo .. rst-class:: classref-property -:ref:`bool` **gutters_draw_executing_lines** = ``false`` +:ref:`bool` **gutters_draw_executing_lines** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_draw_executing_lines_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_executing_lines_gutter**\ (\ ) -Sets if executing lines should be marked in the gutter. This gutter is shared with breakpoints and bookmarks lines. +If ``true``, executing lines are marked in the gutter. This gutter is shared with breakpoints and bookmarks. See :ref:`set_line_as_executing()`. .. rst-class:: classref-item-separator @@ -654,14 +684,14 @@ Sets if executing lines should be marked in the gutter. This gutter is shared wi .. rst-class:: classref-property -:ref:`bool` **gutters_draw_fold_gutter** = ``false`` +:ref:`bool` **gutters_draw_fold_gutter** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_draw_fold_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_fold_gutter**\ (\ ) -Sets if foldable lines icons should be drawn in the gutter. +If ``true``, the fold gutter is drawn. In this gutter, the :ref:`can_fold_code_region` icon is drawn for each foldable line (see :ref:`can_fold_line()`) and the :ref:`folded_code_region` icon is drawn for each folded line (see :ref:`is_line_folded()`). These icons can be clicked to toggle the fold state, see :ref:`toggle_foldable_line()`. :ref:`line_folding` must be ``true`` to show icons. .. rst-class:: classref-item-separator @@ -671,14 +701,14 @@ Sets if foldable lines icons should be drawn in the gutter. .. rst-class:: classref-property -:ref:`bool` **gutters_draw_line_numbers** = ``false`` +:ref:`bool` **gutters_draw_line_numbers** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_draw_line_numbers**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_draw_line_numbers_enabled**\ (\ ) -Sets if line numbers should be drawn in the gutter. +If ``true``, the line number gutter is drawn. Line numbers start at ``1`` and are incremented for each line of text. Clicking and dragging in the line number gutter will select entire lines of text. .. rst-class:: classref-item-separator @@ -688,14 +718,14 @@ Sets if line numbers should be drawn in the gutter. .. rst-class:: classref-property -:ref:`bool` **gutters_zero_pad_line_numbers** = ``false`` +:ref:`bool` **gutters_zero_pad_line_numbers** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_line_numbers_zero_padded**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_line_numbers_zero_padded**\ (\ ) -Sets if line numbers drawn in the gutter are zero padded. +If ``true``, line numbers drawn in the gutter are zero padded based on the total line count. Requires :ref:`gutters_draw_line_numbers` to be set to ``true``. .. rst-class:: classref-item-separator @@ -705,14 +735,14 @@ Sets if line numbers drawn in the gutter are zero padded. .. rst-class:: classref-property -:ref:`bool` **indent_automatic** = ``false`` +:ref:`bool` **indent_automatic** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_indent_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_auto_indent_enabled**\ (\ ) -Sets whether automatic indent are enabled, this will add an extra indent if a prefix or brace is found. +If ``true``, an extra indent is automatically inserted when a new line is added and a prefix in :ref:`indent_automatic_prefixes` is found. If a brace pair opening key is found, the matching closing brace will be moved to another new line (see :ref:`auto_brace_completion_pairs`). .. rst-class:: classref-item-separator @@ -722,14 +752,14 @@ Sets whether automatic indent are enabled, this will add an extra indent if a pr .. rst-class:: classref-property -:ref:`Array`\[:ref:`String`\] **indent_automatic_prefixes** = ``[":", "{", "[", "("]`` +:ref:`Array`\[:ref:`String`\] **indent_automatic_prefixes** = ``[":", "{", "[", "("]`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_indent_prefixes**\ (\ value\: :ref:`Array`\[:ref:`String`\]\ ) - :ref:`Array`\[:ref:`String`\] **get_auto_indent_prefixes**\ (\ ) -Prefixes to trigger an automatic indent. +Prefixes to trigger an automatic indent. Used when :ref:`indent_automatic` is set to ``true``. .. rst-class:: classref-item-separator @@ -739,7 +769,7 @@ Prefixes to trigger an automatic indent. .. rst-class:: classref-property -:ref:`int` **indent_size** = ``4`` +:ref:`int` **indent_size** = ``4`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -756,7 +786,7 @@ Size of the tabulation indent (one :kbd:`Tab` press) in characters. If :ref:`ind .. rst-class:: classref-property -:ref:`bool` **indent_use_spaces** = ``false`` +:ref:`bool` **indent_use_spaces** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -773,14 +803,14 @@ Use spaces instead of tabs for indentation. .. rst-class:: classref-property -:ref:`bool` **line_folding** = ``false`` +:ref:`bool` **line_folding** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_line_folding_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_line_folding_enabled**\ (\ ) -Sets whether line folding is allowed. +If ``true``, lines can be folded. Otherwise, line folding methods like :ref:`fold_line()` will not work and :ref:`can_fold_line()` will always return ``false``. See :ref:`gutters_draw_fold_gutter`. .. rst-class:: classref-item-separator @@ -790,14 +820,14 @@ Sets whether line folding is allowed. .. rst-class:: classref-property -:ref:`Array`\[:ref:`int`\] **line_length_guidelines** = ``[]`` +:ref:`Array`\[:ref:`int`\] **line_length_guidelines** = ``[]`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_line_length_guidelines**\ (\ value\: :ref:`Array`\[:ref:`int`\]\ ) - :ref:`Array`\[:ref:`int`\] **get_line_length_guidelines**\ (\ ) -Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is draw more prominently. +Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is drawn more prominently. .. rst-class:: classref-item-separator @@ -807,7 +837,7 @@ Draws vertical lines at the provided columns. The first entry is considered a ma .. rst-class:: classref-property -:ref:`bool` **symbol_lookup_on_click** = ``false`` +:ref:`bool` **symbol_lookup_on_click** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -816,6 +846,23 @@ Draws vertical lines at the provided columns. The first entry is considered a ma Set when a validated word from :ref:`symbol_validate` is clicked, the :ref:`symbol_lookup` should be emitted. +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_property_symbol_tooltip_on_hover: + +.. rst-class:: classref-property + +:ref:`bool` **symbol_tooltip_on_hover** = ``false`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_symbol_tooltip_on_hover_enabled**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_symbol_tooltip_on_hover_enabled**\ (\ ) + +If ``true``, the :ref:`symbol_hovered` signal is emitted when hovering over a word. + .. rst-class:: classref-section-separator ---- @@ -829,9 +876,9 @@ Method Descriptions .. rst-class:: classref-method -|void| **_confirm_code_completion**\ (\ replace\: :ref:`bool`\ ) |virtual| +|void| **_confirm_code_completion**\ (\ replace\: :ref:`bool`\ ) |virtual| :ref:`🔗` -Override this method to define how the selected entry should be inserted. If ``replace`` is true, any existing text should be replaced. +Override this method to define how the selected entry should be inserted. If ``replace`` is ``true``, any existing text should be replaced. .. rst-class:: classref-item-separator @@ -841,11 +888,11 @@ Override this method to define how the selected entry should be inserted. If ``r .. rst-class:: classref-method -:ref:`Array`\[:ref:`Dictionary`\] **_filter_code_completion_candidates**\ (\ candidates\: :ref:`Array`\[:ref:`Dictionary`\]\ ) |virtual| |const| +:ref:`Array`\[:ref:`Dictionary`\] **_filter_code_completion_candidates**\ (\ candidates\: :ref:`Array`\[:ref:`Dictionary`\]\ ) |virtual| |const| :ref:`🔗` Override this method to define what items in ``candidates`` should be displayed. -Both ``candidates`` and the return is a :ref:`Array` of :ref:`Dictionary`, see :ref:`get_code_completion_option` for :ref:`Dictionary` content. +Both ``candidates`` and the return is an :ref:`Array` of :ref:`Dictionary`, see :ref:`get_code_completion_option()` for :ref:`Dictionary` content. .. rst-class:: classref-item-separator @@ -855,9 +902,9 @@ Both ``candidates`` and the return is a :ref:`Array` of :ref:`Dicti .. rst-class:: classref-method -|void| **_request_code_completion**\ (\ force\: :ref:`bool`\ ) |virtual| +|void| **_request_code_completion**\ (\ force\: :ref:`bool`\ ) |virtual| :ref:`🔗` -Override this method to define what happens when the user requests code completion. If ``force`` is true, any checks should be bypassed. +Override this method to define what happens when the user requests code completion. If ``force`` is ``true``, any checks should be bypassed. .. rst-class:: classref-item-separator @@ -867,7 +914,7 @@ Override this method to define what happens when the user requests code completi .. rst-class:: classref-method -|void| **add_auto_brace_completion_pair**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`\ ) +|void| **add_auto_brace_completion_pair**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`\ ) :ref:`🔗` Adds a brace pair. @@ -881,9 +928,9 @@ Both the start and end keys must be symbols. Only the start key has to be unique .. rst-class:: classref-method -|void| **add_code_completion_option**\ (\ type\: :ref:`CodeCompletionKind`, display_text\: :ref:`String`, insert_text\: :ref:`String`, text_color\: :ref:`Color` = Color(1, 1, 1, 1), icon\: :ref:`Resource` = null, value\: :ref:`Variant` = null, location\: :ref:`int` = 1024\ ) +|void| **add_code_completion_option**\ (\ type\: :ref:`CodeCompletionKind`, display_text\: :ref:`String`, insert_text\: :ref:`String`, text_color\: :ref:`Color` = Color(1, 1, 1, 1), icon\: :ref:`Resource` = null, value\: :ref:`Variant` = null, location\: :ref:`int` = 1024\ ) :ref:`🔗` -Submits an item to the queue of potential candidates for the autocomplete menu. Call :ref:`update_code_completion_options` to update the list. +Submits an item to the queue of potential candidates for the autocomplete menu. Call :ref:`update_code_completion_options()` to update the list. \ ``location`` indicates location of the option relative to the location of the code completion query. See :ref:`CodeCompletionLocation` for how to set this value. @@ -897,7 +944,7 @@ Submits an item to the queue of potential candidates for the autocomplete menu. .. rst-class:: classref-method -|void| **add_comment_delimiter**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) +|void| **add_comment_delimiter**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) :ref:`🔗` Adds a comment delimiter from ``start_key`` to ``end_key``. Both keys should be symbols, and ``start_key`` must not be shared with other delimiters. @@ -911,7 +958,7 @@ If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) +|void| **add_string_delimiter**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, line_only\: :ref:`bool` = false\ ) :ref:`🔗` Defines a string delimiter from ``start_key`` to ``end_key``. Both keys should be symbols, and ``start_key`` must not be shared with other delimiters. @@ -925,9 +972,9 @@ If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String` **can_fold_line**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **can_fold_line**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns if the given line is foldable, that is, it has indented lines right below it or a comment / string block. +Returns ``true`` if the given line is foldable. A line is foldable if it is the start of a valid code region (see :ref:`get_code_region_start_tag()`), if it is the start of a comment or string block, or if the next non-empty line is more indented (see :ref:`TextEdit.get_indent_level()`). .. rst-class:: classref-item-separator @@ -937,7 +984,7 @@ Returns if the given line is foldable, that is, it has indented lines right belo .. rst-class:: classref-method -|void| **cancel_code_completion**\ (\ ) +|void| **cancel_code_completion**\ (\ ) :ref:`🔗` Cancels the autocomplete menu. @@ -949,7 +996,7 @@ Cancels the autocomplete menu. .. rst-class:: classref-method -|void| **clear_bookmarked_lines**\ (\ ) +|void| **clear_bookmarked_lines**\ (\ ) :ref:`🔗` Clears all bookmarked lines. @@ -961,7 +1008,7 @@ Clears all bookmarked lines. .. rst-class:: classref-method -|void| **clear_breakpointed_lines**\ (\ ) +|void| **clear_breakpointed_lines**\ (\ ) :ref:`🔗` Clears all breakpointed lines. @@ -973,7 +1020,7 @@ Clears all breakpointed lines. .. rst-class:: classref-method -|void| **clear_comment_delimiters**\ (\ ) +|void| **clear_comment_delimiters**\ (\ ) :ref:`🔗` Removes all comment delimiters. @@ -985,7 +1032,7 @@ Removes all comment delimiters. .. rst-class:: classref-method -|void| **clear_executing_lines**\ (\ ) +|void| **clear_executing_lines**\ (\ ) :ref:`🔗` Clears all executed lines. @@ -997,7 +1044,7 @@ Clears all executed lines. .. rst-class:: classref-method -|void| **clear_string_delimiters**\ (\ ) +|void| **clear_string_delimiters**\ (\ ) :ref:`🔗` Removes all string delimiters. @@ -1009,9 +1056,9 @@ Removes all string delimiters. .. rst-class:: classref-method -|void| **confirm_code_completion**\ (\ replace\: :ref:`bool` = false\ ) +|void| **confirm_code_completion**\ (\ replace\: :ref:`bool` = false\ ) :ref:`🔗` -Inserts the selected entry into the text. If ``replace`` is true, any existing text is replaced rather than merged. +Inserts the selected entry into the text. If ``replace`` is ``true``, any existing text is replaced rather than merged. .. rst-class:: classref-item-separator @@ -1021,7 +1068,7 @@ Inserts the selected entry into the text. If ``replace`` is true, any existing t .. rst-class:: classref-method -|void| **convert_indent**\ (\ from_line\: :ref:`int` = -1, to_line\: :ref:`int` = -1\ ) +|void| **convert_indent**\ (\ from_line\: :ref:`int` = -1, to_line\: :ref:`int` = -1\ ) :ref:`🔗` Converts the indents of lines between ``from_line`` and ``to_line`` to tabs or spaces as set by :ref:`indent_use_spaces`. @@ -1035,13 +1082,13 @@ Values of ``-1`` convert the entire text. .. rst-class:: classref-method -|void| **create_code_region**\ (\ ) +|void| **create_code_region**\ (\ ) :ref:`🔗` -Creates a new code region with the selection. At least one single line comment delimiter have to be defined (see :ref:`add_comment_delimiter`). +Creates a new code region with the selection. At least one single line comment delimiter have to be defined (see :ref:`add_comment_delimiter()`). A code region is a part of code that is highlighted when folded and can help organize your script. -Code region start and end tags can be customized (see :ref:`set_code_region_tags`). +Code region start and end tags can be customized (see :ref:`set_code_region_tags()`). Code regions are delimited using start and end tags (respectively ``region`` and ``endregion`` by default) preceded by one line comment delimiter. (eg. ``#region`` and ``#endregion``) @@ -1049,13 +1096,25 @@ Code regions are delimited using start and end tags (respectively ``region`` and ---- +.. _class_CodeEdit_method_delete_lines: + +.. rst-class:: classref-method + +|void| **delete_lines**\ (\ ) :ref:`🔗` + +Deletes all lines that are selected or have a caret on them. + +.. rst-class:: classref-item-separator + +---- + .. _class_CodeEdit_method_do_indent: .. rst-class:: classref-method -|void| **do_indent**\ (\ ) +|void| **do_indent**\ (\ ) :ref:`🔗` -Perform an indent as if the user activated the "ui_text_indent" action. +If there is no selection, indentation is inserted at the caret. Otherwise, the selected lines are indented like :ref:`indent_lines()`. Equivalent to the :ref:`ProjectSettings.input/ui_text_indent` action. The indentation characters used depend on :ref:`indent_use_spaces` and :ref:`indent_size`. .. rst-class:: classref-item-separator @@ -1065,7 +1124,7 @@ Perform an indent as if the user activated the "ui_text_indent" action. .. rst-class:: classref-method -|void| **duplicate_lines**\ (\ ) +|void| **duplicate_lines**\ (\ ) :ref:`🔗` Duplicates all lines currently selected with any caret. Duplicates the entire line beneath the current one no matter where the caret is within the line. @@ -1073,13 +1132,25 @@ Duplicates all lines currently selected with any caret. Duplicates the entire li ---- +.. _class_CodeEdit_method_duplicate_selection: + +.. rst-class:: classref-method + +|void| **duplicate_selection**\ (\ ) :ref:`🔗` + +Duplicates all selected text and duplicates all lines with a caret on them. + +.. rst-class:: classref-item-separator + +---- + .. _class_CodeEdit_method_fold_all_lines: .. rst-class:: classref-method -|void| **fold_all_lines**\ (\ ) +|void| **fold_all_lines**\ (\ ) :ref:`🔗` -Folds all lines that are possible to be folded (see :ref:`can_fold_line`). +Folds all lines that are possible to be folded (see :ref:`can_fold_line()`). .. rst-class:: classref-item-separator @@ -1089,9 +1160,9 @@ Folds all lines that are possible to be folded (see :ref:`can_fold_line`\ ) +|void| **fold_line**\ (\ line\: :ref:`int`\ ) :ref:`🔗` -Folds the given line, if possible (see :ref:`can_fold_line`). +Folds the given line, if possible (see :ref:`can_fold_line()`). .. rst-class:: classref-item-separator @@ -1101,7 +1172,7 @@ Folds the given line, if possible (see :ref:`can_fold_line` **get_auto_brace_completion_close_key**\ (\ open_key\: :ref:`String`\ ) |const| +:ref:`String` **get_auto_brace_completion_close_key**\ (\ open_key\: :ref:`String`\ ) |const| :ref:`🔗` Gets the matching auto brace close key for ``open_key``. @@ -1113,7 +1184,7 @@ Gets the matching auto brace close key for ``open_key``. .. rst-class:: classref-method -:ref:`PackedInt32Array` **get_bookmarked_lines**\ (\ ) |const| +:ref:`PackedInt32Array` **get_bookmarked_lines**\ (\ ) |const| :ref:`🔗` Gets all bookmarked lines. @@ -1125,7 +1196,7 @@ Gets all bookmarked lines. .. rst-class:: classref-method -:ref:`PackedInt32Array` **get_breakpointed_lines**\ (\ ) |const| +:ref:`PackedInt32Array` **get_breakpointed_lines**\ (\ ) |const| :ref:`🔗` Gets all breakpointed lines. @@ -1137,7 +1208,7 @@ Gets all breakpointed lines. .. rst-class:: classref-method -:ref:`Dictionary` **get_code_completion_option**\ (\ index\: :ref:`int`\ ) |const| +:ref:`Dictionary` **get_code_completion_option**\ (\ index\: :ref:`int`\ ) |const| :ref:`🔗` Gets the completion option at ``index``. The return :ref:`Dictionary` has the following key-values: @@ -1161,9 +1232,9 @@ Gets the completion option at ``index``. The return :ref:`Dictionary`\[:ref:`Dictionary`\] **get_code_completion_options**\ (\ ) |const| +:ref:`Array`\[:ref:`Dictionary`\] **get_code_completion_options**\ (\ ) |const| :ref:`🔗` -Gets all completion options, see :ref:`get_code_completion_option` for return content. +Gets all completion options, see :ref:`get_code_completion_option()` for return content. .. rst-class:: classref-item-separator @@ -1173,7 +1244,7 @@ Gets all completion options, see :ref:`get_code_completion_option` **get_code_completion_selected_index**\ (\ ) |const| +:ref:`int` **get_code_completion_selected_index**\ (\ ) |const| :ref:`🔗` Gets the index of the current selected completion option. @@ -1185,7 +1256,7 @@ Gets the index of the current selected completion option. .. rst-class:: classref-method -:ref:`String` **get_code_region_end_tag**\ (\ ) |const| +:ref:`String` **get_code_region_end_tag**\ (\ ) |const| :ref:`🔗` Returns the code region end tag (without comment delimiter). @@ -1197,7 +1268,7 @@ Returns the code region end tag (without comment delimiter). .. rst-class:: classref-method -:ref:`String` **get_code_region_start_tag**\ (\ ) |const| +:ref:`String` **get_code_region_start_tag**\ (\ ) |const| :ref:`🔗` Returns the code region start tag (without comment delimiter). @@ -1209,7 +1280,7 @@ Returns the code region start tag (without comment delimiter). .. rst-class:: classref-method -:ref:`String` **get_delimiter_end_key**\ (\ delimiter_index\: :ref:`int`\ ) |const| +:ref:`String` **get_delimiter_end_key**\ (\ delimiter_index\: :ref:`int`\ ) |const| :ref:`🔗` Gets the end key for a string or comment region index. @@ -1221,7 +1292,7 @@ Gets the end key for a string or comment region index. .. rst-class:: classref-method -:ref:`Vector2` **get_delimiter_end_position**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| +:ref:`Vector2` **get_delimiter_end_position**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| :ref:`🔗` If ``line`` ``column`` is in a string or comment, returns the end position of the region. If not or no end could be found, both :ref:`Vector2` values will be ``-1``. @@ -1233,7 +1304,7 @@ If ``line`` ``column`` is in a string or comment, returns the end position of th .. rst-class:: classref-method -:ref:`String` **get_delimiter_start_key**\ (\ delimiter_index\: :ref:`int`\ ) |const| +:ref:`String` **get_delimiter_start_key**\ (\ delimiter_index\: :ref:`int`\ ) |const| :ref:`🔗` Gets the start key for a string or comment region index. @@ -1245,7 +1316,7 @@ Gets the start key for a string or comment region index. .. rst-class:: classref-method -:ref:`Vector2` **get_delimiter_start_position**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| +:ref:`Vector2` **get_delimiter_start_position**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| :ref:`🔗` If ``line`` ``column`` is in a string or comment, returns the start position of the region. If not or no start could be found, both :ref:`Vector2` values will be ``-1``. @@ -1257,7 +1328,7 @@ If ``line`` ``column`` is in a string or comment, returns the start position of .. rst-class:: classref-method -:ref:`PackedInt32Array` **get_executing_lines**\ (\ ) |const| +:ref:`PackedInt32Array` **get_executing_lines**\ (\ ) |const| :ref:`🔗` Gets all executing lines. @@ -1269,9 +1340,9 @@ Gets all executing lines. .. rst-class:: classref-method -:ref:`Array`\[:ref:`int`\] **get_folded_lines**\ (\ ) |const| +:ref:`Array`\[:ref:`int`\] **get_folded_lines**\ (\ ) |const| :ref:`🔗` -Returns all lines that are current folded. +Returns all lines that are currently folded. .. rst-class:: classref-item-separator @@ -1281,7 +1352,7 @@ Returns all lines that are current folded. .. rst-class:: classref-method -:ref:`String` **get_text_for_code_completion**\ (\ ) |const| +:ref:`String` **get_text_for_code_completion**\ (\ ) |const| :ref:`🔗` Returns the full text with char ``0xFFFF`` at the caret location. @@ -1293,7 +1364,7 @@ Returns the full text with char ``0xFFFF`` at the caret location. .. rst-class:: classref-method -:ref:`String` **get_text_for_symbol_lookup**\ (\ ) |const| +:ref:`String` **get_text_for_symbol_lookup**\ (\ ) |const| :ref:`🔗` Returns the full text with char ``0xFFFF`` at the cursor location. @@ -1305,7 +1376,7 @@ Returns the full text with char ``0xFFFF`` at the cursor location. .. rst-class:: classref-method -:ref:`String` **get_text_with_cursor_char**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| +:ref:`String` **get_text_with_cursor_char**\ (\ line\: :ref:`int`, column\: :ref:`int`\ ) |const| :ref:`🔗` Returns the full text with char ``0xFFFF`` at the specified location. @@ -1317,7 +1388,7 @@ Returns the full text with char ``0xFFFF`` at the specified location. .. rst-class:: classref-method -:ref:`bool` **has_auto_brace_completion_close_key**\ (\ close_key\: :ref:`String`\ ) |const| +:ref:`bool` **has_auto_brace_completion_close_key**\ (\ close_key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if close key ``close_key`` exists. @@ -1329,7 +1400,7 @@ Returns ``true`` if close key ``close_key`` exists. .. rst-class:: classref-method -:ref:`bool` **has_auto_brace_completion_open_key**\ (\ open_key\: :ref:`String`\ ) |const| +:ref:`bool` **has_auto_brace_completion_open_key**\ (\ open_key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if open key ``open_key`` exists. @@ -1341,7 +1412,7 @@ Returns ``true`` if open key ``open_key`` exists. .. rst-class:: classref-method -:ref:`bool` **has_comment_delimiter**\ (\ start_key\: :ref:`String`\ ) |const| +:ref:`bool` **has_comment_delimiter**\ (\ start_key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if comment ``start_key`` exists. @@ -1353,7 +1424,7 @@ Returns ``true`` if comment ``start_key`` exists. .. rst-class:: classref-method -:ref:`bool` **has_string_delimiter**\ (\ start_key\: :ref:`String`\ ) |const| +:ref:`bool` **has_string_delimiter**\ (\ start_key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if string ``start_key`` exists. @@ -1365,9 +1436,9 @@ Returns ``true`` if string ``start_key`` exists. .. rst-class:: classref-method -|void| **indent_lines**\ (\ ) +|void| **indent_lines**\ (\ ) :ref:`🔗` -Indents selected lines, or in the case of no selection the caret line by one. +Indents all lines that are selected or have a caret on them. Uses spaces or a tab depending on :ref:`indent_use_spaces`. See :ref:`unindent_lines()`. .. rst-class:: classref-item-separator @@ -1377,7 +1448,7 @@ Indents selected lines, or in the case of no selection the caret line by one. .. rst-class:: classref-method -:ref:`int` **is_in_comment**\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| +:ref:`int` **is_in_comment**\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| :ref:`🔗` Returns delimiter index if ``line`` ``column`` is in a comment. If ``column`` is not provided, will return delimiter index if the entire ``line`` is a comment. Otherwise ``-1``. @@ -1389,7 +1460,7 @@ Returns delimiter index if ``line`` ``column`` is in a comment. If ``column`` is .. rst-class:: classref-method -:ref:`int` **is_in_string**\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| +:ref:`int` **is_in_string**\ (\ line\: :ref:`int`, column\: :ref:`int` = -1\ ) |const| :ref:`🔗` Returns the delimiter index if ``line`` ``column`` is in a string. If ``column`` is not provided, will return the delimiter index if the entire ``line`` is a string. Otherwise ``-1``. @@ -1401,9 +1472,9 @@ Returns the delimiter index if ``line`` ``column`` is in a string. If ``column`` .. rst-class:: classref-method -:ref:`bool` **is_line_bookmarked**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **is_line_bookmarked**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns whether the line at the specified index is bookmarked or not. +Returns ``true`` if the given line is bookmarked. See :ref:`set_line_as_bookmarked()`. .. rst-class:: classref-item-separator @@ -1413,9 +1484,9 @@ Returns whether the line at the specified index is bookmarked or not. .. rst-class:: classref-method -:ref:`bool` **is_line_breakpointed**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **is_line_breakpointed**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns whether the line at the specified index is breakpointed or not. +Returns ``true`` if the given line is breakpointed. See :ref:`set_line_as_breakpoint()`. .. rst-class:: classref-item-separator @@ -1425,9 +1496,9 @@ Returns whether the line at the specified index is breakpointed or not. .. rst-class:: classref-method -:ref:`bool` **is_line_code_region_end**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **is_line_code_region_end**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns whether the line at the specified index is a code region end. +Returns ``true`` if the given line is a code region end. See :ref:`set_code_region_tags()`. .. rst-class:: classref-item-separator @@ -1437,9 +1508,9 @@ Returns whether the line at the specified index is a code region end. .. rst-class:: classref-method -:ref:`bool` **is_line_code_region_start**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **is_line_code_region_start**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns whether the line at the specified index is a code region start. +Returns ``true`` if the given line is a code region start. See :ref:`set_code_region_tags()`. .. rst-class:: classref-item-separator @@ -1449,9 +1520,9 @@ Returns whether the line at the specified index is a code region start. .. rst-class:: classref-method -:ref:`bool` **is_line_executing**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **is_line_executing**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` -Returns whether the line at the specified index is marked as executing or not. +Returns ``true`` if the given line is marked as executing. See :ref:`set_line_as_executing()`. .. rst-class:: classref-item-separator @@ -1461,9 +1532,33 @@ Returns whether the line at the specified index is marked as executing or not. .. rst-class:: classref-method -:ref:`bool` **is_line_folded**\ (\ line\: :ref:`int`\ ) |const| +:ref:`bool` **is_line_folded**\ (\ line\: :ref:`int`\ ) |const| :ref:`🔗` + +Returns ``true`` if the given line is folded. See :ref:`fold_line()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_move_lines_down: + +.. rst-class:: classref-method + +|void| **move_lines_down**\ (\ ) :ref:`🔗` + +Moves all lines down that are selected or have a caret on them. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CodeEdit_method_move_lines_up: + +.. rst-class:: classref-method + +|void| **move_lines_up**\ (\ ) :ref:`🔗` -Returns whether the line at the specified index is folded or not. +Moves all lines up that are selected or have a caret on them. .. rst-class:: classref-item-separator @@ -1473,7 +1568,7 @@ Returns whether the line at the specified index is folded or not. .. rst-class:: classref-method -|void| **remove_comment_delimiter**\ (\ start_key\: :ref:`String`\ ) +|void| **remove_comment_delimiter**\ (\ start_key\: :ref:`String`\ ) :ref:`🔗` Removes the comment delimiter with ``start_key``. @@ -1485,7 +1580,7 @@ Removes the comment delimiter with ``start_key``. .. rst-class:: classref-method -|void| **remove_string_delimiter**\ (\ start_key\: :ref:`String`\ ) +|void| **remove_string_delimiter**\ (\ start_key\: :ref:`String`\ ) :ref:`🔗` Removes the string delimiter with ``start_key``. @@ -1497,9 +1592,9 @@ Removes the string delimiter with ``start_key``. .. rst-class:: classref-method -|void| **request_code_completion**\ (\ force\: :ref:`bool` = false\ ) +|void| **request_code_completion**\ (\ force\: :ref:`bool` = false\ ) :ref:`🔗` -Emits :ref:`code_completion_requested`, if ``force`` is true will bypass all checks. Otherwise will check that the caret is in a word or in front of a prefix. Will ignore the request if all current options are of type file path, node path or signal. +Emits :ref:`code_completion_requested`, if ``force`` is ``true`` will bypass all checks. Otherwise will check that the caret is in a word or in front of a prefix. Will ignore the request if all current options are of type file path, node path, or signal. .. rst-class:: classref-item-separator @@ -1509,7 +1604,7 @@ Emits :ref:`code_completion_requested`\ ) +|void| **set_code_completion_selected_index**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Sets the current selected completion option. @@ -1521,7 +1616,7 @@ Sets the current selected completion option. .. rst-class:: classref-method -|void| **set_code_hint**\ (\ code_hint\: :ref:`String`\ ) +|void| **set_code_hint**\ (\ code_hint\: :ref:`String`\ ) :ref:`🔗` Sets the code hint text. Pass an empty string to clear. @@ -1533,9 +1628,9 @@ Sets the code hint text. Pass an empty string to clear. .. rst-class:: classref-method -|void| **set_code_hint_draw_below**\ (\ draw_below\: :ref:`bool`\ ) +|void| **set_code_hint_draw_below**\ (\ draw_below\: :ref:`bool`\ ) :ref:`🔗` -Sets if the code hint should draw below the text. +If ``true``, the code hint will draw below the main caret. If ``false``, the code hint will draw above the main caret. See :ref:`set_code_hint()`. .. rst-class:: classref-item-separator @@ -1545,7 +1640,7 @@ Sets if the code hint should draw below the text. .. rst-class:: classref-method -|void| **set_code_region_tags**\ (\ start\: :ref:`String` = "region", end\: :ref:`String` = "endregion"\ ) +|void| **set_code_region_tags**\ (\ start\: :ref:`String` = "region", end\: :ref:`String` = "endregion"\ ) :ref:`🔗` Sets the code region start and end tags (without comment delimiter). @@ -1557,9 +1652,9 @@ Sets the code region start and end tags (without comment delimiter). .. rst-class:: classref-method -|void| **set_line_as_bookmarked**\ (\ line\: :ref:`int`, bookmarked\: :ref:`bool`\ ) +|void| **set_line_as_bookmarked**\ (\ line\: :ref:`int`, bookmarked\: :ref:`bool`\ ) :ref:`🔗` -Sets the line as bookmarked. +Sets the given line as bookmarked. If ``true`` and :ref:`gutters_draw_bookmarks` is ``true``, draws the :ref:`bookmark` icon in the gutter for this line. See :ref:`get_bookmarked_lines()` and :ref:`is_line_bookmarked()`. .. rst-class:: classref-item-separator @@ -1569,9 +1664,9 @@ Sets the line as bookmarked. .. rst-class:: classref-method -|void| **set_line_as_breakpoint**\ (\ line\: :ref:`int`, breakpointed\: :ref:`bool`\ ) +|void| **set_line_as_breakpoint**\ (\ line\: :ref:`int`, breakpointed\: :ref:`bool`\ ) :ref:`🔗` -Sets the line as breakpointed. +Sets the given line as a breakpoint. If ``true`` and :ref:`gutters_draw_breakpoints_gutter` is ``true``, draws the :ref:`breakpoint` icon in the gutter for this line. See :ref:`get_breakpointed_lines()` and :ref:`is_line_breakpointed()`. .. rst-class:: classref-item-separator @@ -1581,9 +1676,9 @@ Sets the line as breakpointed. .. rst-class:: classref-method -|void| **set_line_as_executing**\ (\ line\: :ref:`int`, executing\: :ref:`bool`\ ) +|void| **set_line_as_executing**\ (\ line\: :ref:`int`, executing\: :ref:`bool`\ ) :ref:`🔗` -Sets the line as executing. +Sets the given line as executing. If ``true`` and :ref:`gutters_draw_executing_lines` is ``true``, draws the :ref:`executing_line` icon in the gutter for this line. See :ref:`get_executing_lines()` and :ref:`is_line_executing()`. .. rst-class:: classref-item-separator @@ -1593,7 +1688,7 @@ Sets the line as executing. .. rst-class:: classref-method -|void| **set_symbol_lookup_word_as_valid**\ (\ valid\: :ref:`bool`\ ) +|void| **set_symbol_lookup_word_as_valid**\ (\ valid\: :ref:`bool`\ ) :ref:`🔗` Sets the symbol emitted by :ref:`symbol_validate` as a valid lookup. @@ -1605,7 +1700,7 @@ Sets the symbol emitted by :ref:`symbol_validate`\ ) +|void| **toggle_foldable_line**\ (\ line\: :ref:`int`\ ) :ref:`🔗` Toggle the folding of the code block at the given line. @@ -1613,13 +1708,25 @@ Toggle the folding of the code block at the given line. ---- +.. _class_CodeEdit_method_toggle_foldable_lines_at_carets: + +.. rst-class:: classref-method + +|void| **toggle_foldable_lines_at_carets**\ (\ ) :ref:`🔗` + +Toggle the folding of the code block on all lines with a caret on them. + +.. rst-class:: classref-item-separator + +---- + .. _class_CodeEdit_method_unfold_all_lines: .. rst-class:: classref-method -|void| **unfold_all_lines**\ (\ ) +|void| **unfold_all_lines**\ (\ ) :ref:`🔗` -Unfolds all lines, folded or not. +Unfolds all lines that are folded. .. rst-class:: classref-item-separator @@ -1629,9 +1736,9 @@ Unfolds all lines, folded or not. .. rst-class:: classref-method -|void| **unfold_line**\ (\ line\: :ref:`int`\ ) +|void| **unfold_line**\ (\ line\: :ref:`int`\ ) :ref:`🔗` -Unfolds all lines that were previously folded. +Unfolds the given line if it is folded or if it is hidden under a folded line. .. rst-class:: classref-item-separator @@ -1641,9 +1748,9 @@ Unfolds all lines that were previously folded. .. rst-class:: classref-method -|void| **unindent_lines**\ (\ ) +|void| **unindent_lines**\ (\ ) :ref:`🔗` -Unindents selected lines, or in the case of no selection the caret line by one. Same as performing "ui_text_unindent" action. +Unindents all lines that are selected or have a caret on them. Uses spaces or a tab depending on :ref:`indent_use_spaces`. Equivalent to the :ref:`ProjectSettings.input/ui_text_dedent` action. See :ref:`indent_lines()`. .. rst-class:: classref-item-separator @@ -1653,9 +1760,9 @@ Unindents selected lines, or in the case of no selection the caret line by one. .. rst-class:: classref-method -|void| **update_code_completion_options**\ (\ force\: :ref:`bool`\ ) +|void| **update_code_completion_options**\ (\ force\: :ref:`bool`\ ) :ref:`🔗` -Submits all completion options added with :ref:`add_code_completion_option`. Will try to force the autocomplete menu to popup, if ``force`` is ``true``. +Submits all completion options added with :ref:`add_code_completion_option()`. Will try to force the autocomplete menu to popup, if ``force`` is ``true``. \ **Note:** This will replace all current candidates. @@ -1672,7 +1779,7 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Color` **bookmark_color** = ``Color(0.5, 0.64, 1, 0.8)`` +:ref:`Color` **bookmark_color** = ``Color(0.5, 0.64, 1, 0.8)`` :ref:`🔗` :ref:`Color` of the bookmark icon for bookmarked lines. @@ -1684,7 +1791,7 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Color` **brace_mismatch_color** = ``Color(1, 0.2, 0.2, 1)`` +:ref:`Color` **brace_mismatch_color** = ``Color(1, 0.2, 0.2, 1)`` :ref:`🔗` :ref:`Color` of the text to highlight mismatched braces. @@ -1696,7 +1803,7 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Color` **breakpoint_color** = ``Color(0.9, 0.29, 0.3, 1)`` +:ref:`Color` **breakpoint_color** = ``Color(0.9, 0.29, 0.3, 1)`` :ref:`🔗` :ref:`Color` of the breakpoint icon for bookmarked lines. @@ -1708,7 +1815,7 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Color` **code_folding_color** = ``Color(0.8, 0.8, 0.8, 0.8)`` +:ref:`Color` **code_folding_color** = ``Color(0.8, 0.8, 0.8, 0.8)`` :ref:`🔗` :ref:`Color` for all icons related to line folding. @@ -1720,7 +1827,7 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Color` **completion_background_color** = ``Color(0.17, 0.16, 0.2, 1)`` +:ref:`Color` **completion_background_color** = ``Color(0.17, 0.16, 0.2, 1)`` :ref:`🔗` Sets the background :ref:`Color` for the code completion popup. @@ -1732,7 +1839,7 @@ Sets the background :ref:`Color` for the code completion popup. .. rst-class:: classref-themeproperty -:ref:`Color` **completion_existing_color** = ``Color(0.87, 0.87, 0.87, 0.13)`` +:ref:`Color` **completion_existing_color** = ``Color(0.87, 0.87, 0.87, 0.13)`` :ref:`🔗` Background highlight :ref:`Color` for matching text in code completion options. @@ -1744,7 +1851,7 @@ Background highlight :ref:`Color` for matching text in code complet .. rst-class:: classref-themeproperty -:ref:`Color` **completion_scroll_color** = ``Color(1, 1, 1, 0.29)`` +:ref:`Color` **completion_scroll_color** = ``Color(1, 1, 1, 0.29)`` :ref:`🔗` :ref:`Color` of the scrollbar in the code completion popup. @@ -1756,7 +1863,7 @@ Background highlight :ref:`Color` for matching text in code complet .. rst-class:: classref-themeproperty -:ref:`Color` **completion_scroll_hovered_color** = ``Color(1, 1, 1, 0.4)`` +:ref:`Color` **completion_scroll_hovered_color** = ``Color(1, 1, 1, 0.4)`` :ref:`🔗` :ref:`Color` of the scrollbar in the code completion popup when hovered. @@ -1768,7 +1875,7 @@ Background highlight :ref:`Color` for matching text in code complet .. rst-class:: classref-themeproperty -:ref:`Color` **completion_selected_color** = ``Color(0.26, 0.26, 0.27, 1)`` +:ref:`Color` **completion_selected_color** = ``Color(0.26, 0.26, 0.27, 1)`` :ref:`🔗` Background highlight :ref:`Color` for the current selected option item in the code completion popup. @@ -1780,7 +1887,7 @@ Background highlight :ref:`Color` for the current selected option i .. rst-class:: classref-themeproperty -:ref:`Color` **executing_line_color** = ``Color(0.98, 0.89, 0.27, 1)`` +:ref:`Color` **executing_line_color** = ``Color(0.98, 0.89, 0.27, 1)`` :ref:`🔗` :ref:`Color` of the executing icon for executing lines. @@ -1792,7 +1899,7 @@ Background highlight :ref:`Color` for the current selected option i .. rst-class:: classref-themeproperty -:ref:`Color` **folded_code_region_color** = ``Color(0.68, 0.46, 0.77, 0.2)`` +:ref:`Color` **folded_code_region_color** = ``Color(0.68, 0.46, 0.77, 0.2)`` :ref:`🔗` :ref:`Color` of background line highlight for folded code region. @@ -1804,7 +1911,7 @@ Background highlight :ref:`Color` for the current selected option i .. rst-class:: classref-themeproperty -:ref:`Color` **line_length_guideline_color** = ``Color(0.3, 0.5, 0.8, 0.1)`` +:ref:`Color` **line_length_guideline_color** = ``Color(0.3, 0.5, 0.8, 0.1)`` :ref:`🔗` :ref:`Color` of the main line length guideline, secondary guidelines will have 50% alpha applied. @@ -1816,7 +1923,7 @@ Background highlight :ref:`Color` for the current selected option i .. rst-class:: classref-themeproperty -:ref:`Color` **line_number_color** = ``Color(0.67, 0.67, 0.67, 0.4)`` +:ref:`Color` **line_number_color** = ``Color(0.67, 0.67, 0.67, 0.4)`` :ref:`🔗` Sets the :ref:`Color` of line numbers. @@ -1828,7 +1935,7 @@ Sets the :ref:`Color` of line numbers. .. rst-class:: classref-themeproperty -:ref:`int` **completion_lines** = ``7`` +:ref:`int` **completion_lines** = ``7`` :ref:`🔗` Max number of options to display in the code completion popup at any one time. @@ -1840,7 +1947,7 @@ Max number of options to display in the code completion popup at any one time. .. rst-class:: classref-themeproperty -:ref:`int` **completion_max_width** = ``50`` +:ref:`int` **completion_max_width** = ``50`` :ref:`🔗` Max width of options in the code completion popup. Options longer than this will be cut off. @@ -1852,7 +1959,7 @@ Max width of options in the code completion popup. Options longer than this will .. rst-class:: classref-themeproperty -:ref:`int` **completion_scroll_width** = ``6`` +:ref:`int` **completion_scroll_width** = ``6`` :ref:`🔗` Width of the scrollbar in the code completion popup. @@ -1864,7 +1971,7 @@ Width of the scrollbar in the code completion popup. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **bookmark** +:ref:`Texture2D` **bookmark** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw in the bookmark gutter for bookmarked lines. @@ -1876,7 +1983,7 @@ Sets a custom :ref:`Texture2D` to draw in the bookmark gutter f .. rst-class:: classref-themeproperty -:ref:`Texture2D` **breakpoint** +:ref:`Texture2D` **breakpoint** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw in the breakpoint gutter for breakpointed lines. @@ -1888,7 +1995,7 @@ Sets a custom :ref:`Texture2D` to draw in the breakpoint gutter .. rst-class:: classref-themeproperty -:ref:`Texture2D` **can_fold** +:ref:`Texture2D` **can_fold** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a line can be folded. @@ -1900,7 +2007,7 @@ Sets a custom :ref:`Texture2D` to draw in the line folding gutt .. rst-class:: classref-themeproperty -:ref:`Texture2D` **can_fold_code_region** +:ref:`Texture2D` **can_fold_code_region** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a code region can be folded. @@ -1908,11 +2015,23 @@ Sets a custom :ref:`Texture2D` to draw in the line folding gutt ---- +.. _class_CodeEdit_theme_icon_completion_color_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **completion_color_bg** :ref:`🔗` + +Background panel for the color preview box in autocompletion (visible when the color is translucent). + +.. rst-class:: classref-item-separator + +---- + .. _class_CodeEdit_theme_icon_executing_line: .. rst-class:: classref-themeproperty -:ref:`Texture2D` **executing_line** +:ref:`Texture2D` **executing_line** :ref:`🔗` Icon to draw in the executing gutter for executing lines. @@ -1924,7 +2043,7 @@ Icon to draw in the executing gutter for executing lines. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **folded** +:ref:`Texture2D` **folded** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a line is folded and can be unfolded. @@ -1936,7 +2055,7 @@ Sets a custom :ref:`Texture2D` to draw in the line folding gutt .. rst-class:: classref-themeproperty -:ref:`Texture2D` **folded_code_region** +:ref:`Texture2D` **folded_code_region** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw in the line folding gutter when a code region is folded and can be unfolded. @@ -1948,7 +2067,7 @@ Sets a custom :ref:`Texture2D` to draw in the line folding gutt .. rst-class:: classref-themeproperty -:ref:`Texture2D` **folded_eol_icon** +:ref:`Texture2D` **folded_eol_icon** :ref:`🔗` Sets a custom :ref:`Texture2D` to draw at the end of a folded line. @@ -1960,11 +2079,12 @@ Sets a custom :ref:`Texture2D` to draw at the end of a folded l .. rst-class:: classref-themeproperty -:ref:`StyleBox` **completion** +:ref:`StyleBox` **completion** :ref:`🔗` :ref:`StyleBox` for the code completion popup. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_codehighlighter.rst b/classes/class_codehighlighter.rst index 582b59eb7ba..88147fd276d 100644 --- a/classes/class_codehighlighter.rst +++ b/classes/class_codehighlighter.rst @@ -96,7 +96,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Dictionary` **color_regions** = ``{}`` +:ref:`Dictionary` **color_regions** = ``{}`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -113,7 +113,7 @@ Sets the color regions. All existing regions will be removed. The :ref:`Dictiona .. rst-class:: classref-property -:ref:`Color` **function_color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **function_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -130,7 +130,7 @@ Sets color for functions. A function is a non-keyword string followed by a '('. .. rst-class:: classref-property -:ref:`Dictionary` **keyword_colors** = ``{}`` +:ref:`Dictionary` **keyword_colors** = ``{}`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -147,7 +147,7 @@ Sets the keyword colors. All existing keywords will be removed. The :ref:`Dictio .. rst-class:: classref-property -:ref:`Dictionary` **member_keyword_colors** = ``{}`` +:ref:`Dictionary` **member_keyword_colors** = ``{}`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -164,7 +164,7 @@ Sets the member keyword colors. All existing member keyword will be removed. The .. rst-class:: classref-property -:ref:`Color` **member_variable_color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **member_variable_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -181,7 +181,7 @@ Sets color for member variables. A member variable is non-keyword, non-function .. rst-class:: classref-property -:ref:`Color` **number_color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **number_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -198,7 +198,7 @@ Sets the color for numbers. .. rst-class:: classref-property -:ref:`Color` **symbol_color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **symbol_color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -220,7 +220,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_color_region**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, color\: :ref:`Color`, line_only\: :ref:`bool` = false\ ) +|void| **add_color_region**\ (\ start_key\: :ref:`String`, end_key\: :ref:`String`, color\: :ref:`Color`, line_only\: :ref:`bool` = false\ ) :ref:`🔗` Adds a color region (such as for comments or strings) from ``start_key`` to ``end_key``. Both keys should be symbols, and ``start_key`` must not be shared with other delimiters. @@ -234,7 +234,7 @@ If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String`, color\: :ref:`Color`\ ) +|void| **add_keyword_color**\ (\ keyword\: :ref:`String`, color\: :ref:`Color`\ ) :ref:`🔗` Sets the color for a keyword. @@ -248,7 +248,7 @@ The keyword cannot contain any symbols except '\_'. .. rst-class:: classref-method -|void| **add_member_keyword_color**\ (\ member_keyword\: :ref:`String`, color\: :ref:`Color`\ ) +|void| **add_member_keyword_color**\ (\ member_keyword\: :ref:`String`, color\: :ref:`Color`\ ) :ref:`🔗` Sets the color for a member keyword. @@ -264,7 +264,7 @@ It will not be highlighted if preceded by a '.'. .. rst-class:: classref-method -|void| **clear_color_regions**\ (\ ) +|void| **clear_color_regions**\ (\ ) :ref:`🔗` Removes all color regions. @@ -276,7 +276,7 @@ Removes all color regions. .. rst-class:: classref-method -|void| **clear_keyword_colors**\ (\ ) +|void| **clear_keyword_colors**\ (\ ) :ref:`🔗` Removes all keywords. @@ -288,7 +288,7 @@ Removes all keywords. .. rst-class:: classref-method -|void| **clear_member_keyword_colors**\ (\ ) +|void| **clear_member_keyword_colors**\ (\ ) :ref:`🔗` Removes all member keywords. @@ -300,7 +300,7 @@ Removes all member keywords. .. rst-class:: classref-method -:ref:`Color` **get_keyword_color**\ (\ keyword\: :ref:`String`\ ) |const| +:ref:`Color` **get_keyword_color**\ (\ keyword\: :ref:`String`\ ) |const| :ref:`🔗` Returns the color for a keyword. @@ -312,7 +312,7 @@ Returns the color for a keyword. .. rst-class:: classref-method -:ref:`Color` **get_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) |const| +:ref:`Color` **get_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) |const| :ref:`🔗` Returns the color for a member keyword. @@ -324,7 +324,7 @@ Returns the color for a member keyword. .. rst-class:: classref-method -:ref:`bool` **has_color_region**\ (\ start_key\: :ref:`String`\ ) |const| +:ref:`bool` **has_color_region**\ (\ start_key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the start key exists, else ``false``. @@ -336,7 +336,7 @@ Returns ``true`` if the start key exists, else ``false``. .. rst-class:: classref-method -:ref:`bool` **has_keyword_color**\ (\ keyword\: :ref:`String`\ ) |const| +:ref:`bool` **has_keyword_color**\ (\ keyword\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the keyword exists, else ``false``. @@ -348,7 +348,7 @@ Returns ``true`` if the keyword exists, else ``false``. .. rst-class:: classref-method -:ref:`bool` **has_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) |const| +:ref:`bool` **has_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the member keyword exists, else ``false``. @@ -360,7 +360,7 @@ Returns ``true`` if the member keyword exists, else ``false``. .. rst-class:: classref-method -|void| **remove_color_region**\ (\ start_key\: :ref:`String`\ ) +|void| **remove_color_region**\ (\ start_key\: :ref:`String`\ ) :ref:`🔗` Removes the color region that uses that start key. @@ -372,7 +372,7 @@ Removes the color region that uses that start key. .. rst-class:: classref-method -|void| **remove_keyword_color**\ (\ keyword\: :ref:`String`\ ) +|void| **remove_keyword_color**\ (\ keyword\: :ref:`String`\ ) :ref:`🔗` Removes the keyword. @@ -384,11 +384,12 @@ Removes the keyword. .. rst-class:: classref-method -|void| **remove_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) +|void| **remove_member_keyword_color**\ (\ member_keyword\: :ref:`String`\ ) :ref:`🔗` Removes the member keyword. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_collisionobject2d.rst b/classes/class_collisionobject2d.rst index 5100fa0bc75..f17ca4c4dba 100644 --- a/classes/class_collisionobject2d.rst +++ b/classes/class_collisionobject2d.rst @@ -126,9 +126,9 @@ Signals .. rst-class:: classref-signal -**input_event**\ (\ viewport\: :ref:`Node`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) +**input_event**\ (\ viewport\: :ref:`Node`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) :ref:`🔗` -Emitted when an input event occurs. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. See :ref:`_input_event` for details. +Emitted when an input event occurs. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. See :ref:`_input_event()` for details. .. rst-class:: classref-item-separator @@ -138,7 +138,7 @@ Emitted when an input event occurs. Requires :ref:`input_pickable` Emitted when the mouse pointer enters any of this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this signal to be emitted. @@ -152,7 +152,7 @@ Emitted when the mouse pointer enters any of this object's shapes. Requires :ref .. rst-class:: classref-signal -**mouse_exited**\ (\ ) +**mouse_exited**\ (\ ) :ref:`🔗` Emitted when the mouse pointer exits all this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this signal to be emitted. @@ -166,7 +166,7 @@ Emitted when the mouse pointer exits all this object's shapes. Requires :ref:`in .. rst-class:: classref-signal -**mouse_shape_entered**\ (\ shape_idx\: :ref:`int`\ ) +**mouse_shape_entered**\ (\ shape_idx\: :ref:`int`\ ) :ref:`🔗` Emitted when the mouse pointer enters any of this object's shapes or moves from one shape to another. ``shape_idx`` is the child index of the newly entered :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. @@ -178,7 +178,7 @@ Emitted when the mouse pointer enters any of this object's shapes or moves from .. rst-class:: classref-signal -**mouse_shape_exited**\ (\ shape_idx\: :ref:`int`\ ) +**mouse_shape_exited**\ (\ shape_idx\: :ref:`int`\ ) :ref:`🔗` Emitted when the mouse pointer exits any of this object's shapes. ``shape_idx`` is the child index of the exited :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. @@ -195,7 +195,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **DisableMode**: +enum **DisableMode**: :ref:`🔗` .. _class_CollisionObject2D_constant_DISABLE_MODE_REMOVE: @@ -238,7 +238,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **collision_layer** = ``1`` +:ref:`int` **collision_layer** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -257,7 +257,7 @@ The physics layers this CollisionObject2D is in. Collision objects can exist in .. rst-class:: classref-property -:ref:`int` **collision_mask** = ``1`` +:ref:`int` **collision_mask** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -276,7 +276,7 @@ The physics layers this CollisionObject2D scans. Collision objects can scan one .. rst-class:: classref-property -:ref:`float` **collision_priority** = ``1.0`` +:ref:`float` **collision_priority** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -293,14 +293,14 @@ The priority used to solve colliding when occurring penetration. The higher the .. rst-class:: classref-property -:ref:`DisableMode` **disable_mode** = ``0`` +:ref:`DisableMode` **disable_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_disable_mode**\ (\ value\: :ref:`DisableMode`\ ) - :ref:`DisableMode` **get_disable_mode**\ (\ ) -Defines the behavior in physics when :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`. See :ref:`DisableMode` for more details about the different modes. +Defines the behavior in physics when :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`. .. rst-class:: classref-item-separator @@ -310,7 +310,7 @@ Defines the behavior in physics when :ref:`Node.process_mode` **input_pickable** = ``true`` +:ref:`bool` **input_pickable** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -332,11 +332,11 @@ Method Descriptions .. rst-class:: classref-method -|void| **_input_event**\ (\ viewport\: :ref:`Viewport`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) |virtual| +|void| **_input_event**\ (\ viewport\: :ref:`Viewport`, event\: :ref:`InputEvent`, shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` Accepts unhandled :ref:`InputEvent`\ s. ``shape_idx`` is the child index of the clicked :ref:`Shape2D`. Connect to :ref:`input_event` to easily pick up these events. -\ **Note:** :ref:`_input_event` requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. +\ **Note:** :ref:`_input_event()` requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. .. rst-class:: classref-item-separator @@ -346,7 +346,7 @@ Accepts unhandled :ref:`InputEvent`\ s. ``shape_idx`` is the c .. rst-class:: classref-method -|void| **_mouse_enter**\ (\ ) |virtual| +|void| **_mouse_enter**\ (\ ) |virtual| :ref:`🔗` Called when the mouse pointer enters any of this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this function to be called. @@ -358,7 +358,7 @@ Called when the mouse pointer enters any of this object's shapes. Requires :ref: .. rst-class:: classref-method -|void| **_mouse_exit**\ (\ ) |virtual| +|void| **_mouse_exit**\ (\ ) |virtual| :ref:`🔗` Called when the mouse pointer exits all this object's shapes. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this function to be called. @@ -370,7 +370,7 @@ Called when the mouse pointer exits all this object's shapes. Requires :ref:`inp .. rst-class:: classref-method -|void| **_mouse_shape_enter**\ (\ shape_idx\: :ref:`int`\ ) |virtual| +|void| **_mouse_shape_enter**\ (\ shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` Called when the mouse pointer enters any of this object's shapes or moves from one shape to another. ``shape_idx`` is the child index of the newly entered :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be called. @@ -382,7 +382,7 @@ Called when the mouse pointer enters any of this object's shapes or moves from o .. rst-class:: classref-method -|void| **_mouse_shape_exit**\ (\ shape_idx\: :ref:`int`\ ) |virtual| +|void| **_mouse_shape_exit**\ (\ shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` Called when the mouse pointer exits any of this object's shapes. ``shape_idx`` is the child index of the exited :ref:`Shape2D`. Requires :ref:`input_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be called. @@ -394,7 +394,7 @@ Called when the mouse pointer exits any of this object's shapes. ``shape_idx`` i .. rst-class:: classref-method -:ref:`int` **create_shape_owner**\ (\ owner\: :ref:`Object`\ ) +:ref:`int` **create_shape_owner**\ (\ owner\: :ref:`Object`\ ) :ref:`🔗` Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. @@ -406,7 +406,7 @@ Creates a new shape owner for the given object. Returns ``owner_id`` of the new .. rst-class:: classref-method -:ref:`bool` **get_collision_layer_value**\ (\ layer_number\: :ref:`int`\ ) |const| +:ref:`bool` **get_collision_layer_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether or not the specified layer of the :ref:`collision_layer` is enabled, given a ``layer_number`` between 1 and 32. @@ -418,7 +418,7 @@ Returns whether or not the specified layer of the :ref:`collision_layer` **get_collision_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| +:ref:`bool` **get_collision_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether or not the specified layer of the :ref:`collision_mask` is enabled, given a ``layer_number`` between 1 and 32. @@ -430,7 +430,7 @@ Returns whether or not the specified layer of the :ref:`collision_mask` **get_rid**\ (\ ) |const| +:ref:`RID` **get_rid**\ (\ ) |const| :ref:`🔗` Returns the object's :ref:`RID`. @@ -442,7 +442,7 @@ Returns the object's :ref:`RID`. .. rst-class:: classref-method -:ref:`float` **get_shape_owner_one_way_collision_margin**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`float` **get_shape_owner_one_way_collision_margin**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the ``one_way_collision_margin`` of the shape owner identified by given ``owner_id``. @@ -454,7 +454,7 @@ Returns the ``one_way_collision_margin`` of the shape owner identified by given .. rst-class:: classref-method -:ref:`PackedInt32Array` **get_shape_owners**\ (\ ) +:ref:`PackedInt32Array` **get_shape_owners**\ (\ ) :ref:`🔗` Returns an :ref:`Array` of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. @@ -466,7 +466,7 @@ Returns an :ref:`Array` of ``owner_id`` identifiers. You can use th .. rst-class:: classref-method -:ref:`bool` **is_shape_owner_disabled**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`bool` **is_shape_owner_disabled**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the shape owner and its shapes are disabled. @@ -478,7 +478,7 @@ If ``true``, the shape owner and its shapes are disabled. .. rst-class:: classref-method -:ref:`bool` **is_shape_owner_one_way_collision_enabled**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`bool` **is_shape_owner_one_way_collision_enabled**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns ``true`` if collisions for the shape owner originating from this **CollisionObject2D** will not be reported to collided with **CollisionObject2D**\ s. @@ -490,7 +490,7 @@ Returns ``true`` if collisions for the shape owner originating from this **Colli .. rst-class:: classref-method -|void| **remove_shape_owner**\ (\ owner_id\: :ref:`int`\ ) +|void| **remove_shape_owner**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` Removes the given shape owner. @@ -502,7 +502,7 @@ Removes the given shape owner. .. rst-class:: classref-method -|void| **set_collision_layer_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) +|void| **set_collision_layer_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` Based on ``value``, enables or disables the specified layer in the :ref:`collision_layer`, given a ``layer_number`` between 1 and 32. @@ -514,7 +514,7 @@ Based on ``value``, enables or disables the specified layer in the :ref:`collisi .. rst-class:: classref-method -|void| **set_collision_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) +|void| **set_collision_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` Based on ``value``, enables or disables the specified layer in the :ref:`collision_mask`, given a ``layer_number`` between 1 and 32. @@ -526,7 +526,7 @@ Based on ``value``, enables or disables the specified layer in the :ref:`collisi .. rst-class:: classref-method -:ref:`int` **shape_find_owner**\ (\ shape_index\: :ref:`int`\ ) |const| +:ref:`int` **shape_find_owner**\ (\ shape_index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the ``owner_id`` of the given shape. @@ -538,7 +538,7 @@ Returns the ``owner_id`` of the given shape. .. rst-class:: classref-method -|void| **shape_owner_add_shape**\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape2D`\ ) +|void| **shape_owner_add_shape**\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape2D`\ ) :ref:`🔗` Adds a :ref:`Shape2D` to the shape owner. @@ -550,7 +550,7 @@ Adds a :ref:`Shape2D` to the shape owner. .. rst-class:: classref-method -|void| **shape_owner_clear_shapes**\ (\ owner_id\: :ref:`int`\ ) +|void| **shape_owner_clear_shapes**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` Removes all shapes from the shape owner. @@ -562,7 +562,7 @@ Removes all shapes from the shape owner. .. rst-class:: classref-method -:ref:`Object` **shape_owner_get_owner**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`Object` **shape_owner_get_owner**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the parent object of the given shape owner. @@ -574,7 +574,7 @@ Returns the parent object of the given shape owner. .. rst-class:: classref-method -:ref:`Shape2D` **shape_owner_get_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| +:ref:`Shape2D` **shape_owner_get_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the :ref:`Shape2D` with the given ID from the given shape owner. @@ -586,7 +586,7 @@ Returns the :ref:`Shape2D` with the given ID from the given shape .. rst-class:: classref-method -:ref:`int` **shape_owner_get_shape_count**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`int` **shape_owner_get_shape_count**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the number of shapes the given shape owner contains. @@ -598,7 +598,7 @@ Returns the number of shapes the given shape owner contains. .. rst-class:: classref-method -:ref:`int` **shape_owner_get_shape_index**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| +:ref:`int` **shape_owner_get_shape_index**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the child index of the :ref:`Shape2D` with the given ID from the given shape owner. @@ -610,7 +610,7 @@ Returns the child index of the :ref:`Shape2D` with the given ID f .. rst-class:: classref-method -:ref:`Transform2D` **shape_owner_get_transform**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`Transform2D` **shape_owner_get_transform**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the shape owner's :ref:`Transform2D`. @@ -622,7 +622,7 @@ Returns the shape owner's :ref:`Transform2D`. .. rst-class:: classref-method -|void| **shape_owner_remove_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) +|void| **shape_owner_remove_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) :ref:`🔗` Removes a shape from the given shape owner. @@ -634,7 +634,7 @@ Removes a shape from the given shape owner. .. rst-class:: classref-method -|void| **shape_owner_set_disabled**\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) +|void| **shape_owner_set_disabled**\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) :ref:`🔗` If ``true``, disables the given shape owner. @@ -646,7 +646,7 @@ If ``true``, disables the given shape owner. .. rst-class:: classref-method -|void| **shape_owner_set_one_way_collision**\ (\ owner_id\: :ref:`int`, enable\: :ref:`bool`\ ) +|void| **shape_owner_set_one_way_collision**\ (\ owner_id\: :ref:`int`, enable\: :ref:`bool`\ ) :ref:`🔗` If ``enable`` is ``true``, collisions for the shape owner originating from this **CollisionObject2D** will not be reported to collided with **CollisionObject2D**\ s. @@ -658,7 +658,7 @@ If ``enable`` is ``true``, collisions for the shape owner originating from this .. rst-class:: classref-method -|void| **shape_owner_set_one_way_collision_margin**\ (\ owner_id\: :ref:`int`, margin\: :ref:`float`\ ) +|void| **shape_owner_set_one_way_collision_margin**\ (\ owner_id\: :ref:`int`, margin\: :ref:`float`\ ) :ref:`🔗` Sets the ``one_way_collision_margin`` of the shape owner identified by given ``owner_id`` to ``margin`` pixels. @@ -670,11 +670,12 @@ Sets the ``one_way_collision_margin`` of the shape owner identified by given ``o .. rst-class:: classref-method -|void| **shape_owner_set_transform**\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform2D`\ ) +|void| **shape_owner_set_transform**\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform2D`\ ) :ref:`🔗` Sets the :ref:`Transform2D` of the given shape owner. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_collisionobject3d.rst b/classes/class_collisionobject3d.rst index 06e2beb1c3f..2760df168bc 100644 --- a/classes/class_collisionobject3d.rst +++ b/classes/class_collisionobject3d.rst @@ -55,53 +55,53 @@ Methods .. table:: :widths: auto - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_input_event`\ (\ camera\: :ref:`Camera3D`, event\: :ref:`InputEvent`, position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) |virtual| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_mouse_enter`\ (\ ) |virtual| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`_mouse_exit`\ (\ ) |virtual| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`create_shape_owner`\ (\ owner\: :ref:`Object`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_collision_layer_value`\ (\ layer_number\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_collision_mask_value`\ (\ layer_number\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`RID` | :ref:`get_rid`\ (\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedInt32Array` | :ref:`get_shape_owners`\ (\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_shape_owner_disabled`\ (\ owner_id\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`remove_shape_owner`\ (\ owner_id\: :ref:`int`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_collision_layer_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_collision_mask_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`shape_find_owner`\ (\ shape_index\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`shape_owner_add_shape`\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape3D`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`shape_owner_clear_shapes`\ (\ owner_id\: :ref:`int`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Object` | :ref:`shape_owner_get_owner`\ (\ owner_id\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Shape3D` | :ref:`shape_owner_get_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`shape_owner_get_shape_count`\ (\ owner_id\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`int` | :ref:`shape_owner_get_shape_index`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Transform3D` | :ref:`shape_owner_get_transform`\ (\ owner_id\: :ref:`int`\ ) |const| | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`shape_owner_remove_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`shape_owner_set_disabled`\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`shape_owner_set_transform`\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform3D`\ ) | - +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_input_event`\ (\ camera\: :ref:`Camera3D`, event\: :ref:`InputEvent`, event_position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) |virtual| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_enter`\ (\ ) |virtual| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`_mouse_exit`\ (\ ) |virtual| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`create_shape_owner`\ (\ owner\: :ref:`Object`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_collision_layer_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_collision_mask_value`\ (\ layer_number\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`RID` | :ref:`get_rid`\ (\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedInt32Array` | :ref:`get_shape_owners`\ (\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_shape_owner_disabled`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_shape_owner`\ (\ owner_id\: :ref:`int`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_collision_layer_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_collision_mask_value`\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_find_owner`\ (\ shape_index\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_add_shape`\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape3D`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_clear_shapes`\ (\ owner_id\: :ref:`int`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Object` | :ref:`shape_owner_get_owner`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Shape3D` | :ref:`shape_owner_get_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_owner_get_shape_count`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`shape_owner_get_shape_index`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Transform3D` | :ref:`shape_owner_get_transform`\ (\ owner_id\: :ref:`int`\ ) |const| | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_remove_shape`\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_disabled`\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`shape_owner_set_transform`\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform3D`\ ) | + +-------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -116,9 +116,9 @@ Signals .. rst-class:: classref-signal -**input_event**\ (\ camera\: :ref:`Node`, event\: :ref:`InputEvent`, position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) +**input_event**\ (\ camera\: :ref:`Node`, event\: :ref:`InputEvent`, event_position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) :ref:`🔗` -Emitted when the object receives an unhandled :ref:`InputEvent`. ``position`` is the location in world space of the mouse pointer on the surface of the shape with index ``shape_idx`` and ``normal`` is the normal vector of the surface at that point. +Emitted when the object receives an unhandled :ref:`InputEvent`. ``event_position`` is the location in world space of the mouse pointer on the surface of the shape with index ``shape_idx`` and ``normal`` is the normal vector of the surface at that point. .. rst-class:: classref-item-separator @@ -128,7 +128,7 @@ Emitted when the object receives an unhandled :ref:`InputEvent .. rst-class:: classref-signal -**mouse_entered**\ (\ ) +**mouse_entered**\ (\ ) :ref:`🔗` Emitted when the mouse pointer enters any of this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. @@ -142,7 +142,7 @@ Emitted when the mouse pointer enters any of this object's shapes. Requires :ref .. rst-class:: classref-signal -**mouse_exited**\ (\ ) +**mouse_exited**\ (\ ) :ref:`🔗` Emitted when the mouse pointer exits all this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. @@ -161,7 +161,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **DisableMode**: +enum **DisableMode**: :ref:`🔗` .. _class_CollisionObject3D_constant_DISABLE_MODE_REMOVE: @@ -204,7 +204,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`int` **collision_layer** = ``1`` +:ref:`int` **collision_layer** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -223,7 +223,7 @@ The physics layers this CollisionObject3D **is in**. Collision objects can exist .. rst-class:: classref-property -:ref:`int` **collision_mask** = ``1`` +:ref:`int` **collision_mask** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -242,7 +242,7 @@ The physics layers this CollisionObject3D **scans**. Collision objects can scan .. rst-class:: classref-property -:ref:`float` **collision_priority** = ``1.0`` +:ref:`float` **collision_priority** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -259,14 +259,14 @@ The priority used to solve colliding when occurring penetration. The higher the .. rst-class:: classref-property -:ref:`DisableMode` **disable_mode** = ``0`` +:ref:`DisableMode` **disable_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_disable_mode**\ (\ value\: :ref:`DisableMode`\ ) - :ref:`DisableMode` **get_disable_mode**\ (\ ) -Defines the behavior in physics when :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`. See :ref:`DisableMode` for more details about the different modes. +Defines the behavior in physics when :ref:`Node.process_mode` is set to :ref:`Node.PROCESS_MODE_DISABLED`. .. rst-class:: classref-item-separator @@ -276,7 +276,7 @@ Defines the behavior in physics when :ref:`Node.process_mode` **input_capture_on_drag** = ``false`` +:ref:`bool` **input_capture_on_drag** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -293,7 +293,7 @@ If ``true``, the **CollisionObject3D** will continue to receive input events as .. rst-class:: classref-property -:ref:`bool` **input_ray_pickable** = ``true`` +:ref:`bool` **input_ray_pickable** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -315,11 +315,11 @@ Method Descriptions .. rst-class:: classref-method -|void| **_input_event**\ (\ camera\: :ref:`Camera3D`, event\: :ref:`InputEvent`, position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) |virtual| +|void| **_input_event**\ (\ camera\: :ref:`Camera3D`, event\: :ref:`InputEvent`, event_position\: :ref:`Vector3`, normal\: :ref:`Vector3`, shape_idx\: :ref:`int`\ ) |virtual| :ref:`🔗` -Receives unhandled :ref:`InputEvent`\ s. ``position`` is the location in world space of the mouse pointer on the surface of the shape with index ``shape_idx`` and ``normal`` is the normal vector of the surface at that point. Connect to the :ref:`input_event` signal to easily pick up these events. +Receives unhandled :ref:`InputEvent`\ s. ``event_position`` is the location in world space of the mouse pointer on the surface of the shape with index ``shape_idx`` and ``normal`` is the normal vector of the surface at that point. Connect to the :ref:`input_event` signal to easily pick up these events. -\ **Note:** :ref:`_input_event` requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. +\ **Note:** :ref:`_input_event()` requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. .. rst-class:: classref-item-separator @@ -329,7 +329,7 @@ Receives unhandled :ref:`InputEvent`\ s. ``position`` is the l .. rst-class:: classref-method -|void| **_mouse_enter**\ (\ ) |virtual| +|void| **_mouse_enter**\ (\ ) |virtual| :ref:`🔗` Called when the mouse pointer enters any of this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject3D** won't cause this function to be called. @@ -341,7 +341,7 @@ Called when the mouse pointer enters any of this object's shapes. Requires :ref: .. rst-class:: classref-method -|void| **_mouse_exit**\ (\ ) |virtual| +|void| **_mouse_exit**\ (\ ) |virtual| :ref:`🔗` Called when the mouse pointer exits all this object's shapes. Requires :ref:`input_ray_pickable` to be ``true`` and at least one :ref:`collision_layer` bit to be set. Note that moving between different shapes within a single **CollisionObject3D** won't cause this function to be called. @@ -353,7 +353,7 @@ Called when the mouse pointer exits all this object's shapes. Requires :ref:`inp .. rst-class:: classref-method -:ref:`int` **create_shape_owner**\ (\ owner\: :ref:`Object`\ ) +:ref:`int` **create_shape_owner**\ (\ owner\: :ref:`Object`\ ) :ref:`🔗` Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. @@ -365,7 +365,7 @@ Creates a new shape owner for the given object. Returns ``owner_id`` of the new .. rst-class:: classref-method -:ref:`bool` **get_collision_layer_value**\ (\ layer_number\: :ref:`int`\ ) |const| +:ref:`bool` **get_collision_layer_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether or not the specified layer of the :ref:`collision_layer` is enabled, given a ``layer_number`` between 1 and 32. @@ -377,7 +377,7 @@ Returns whether or not the specified layer of the :ref:`collision_layer` **get_collision_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| +:ref:`bool` **get_collision_mask_value**\ (\ layer_number\: :ref:`int`\ ) |const| :ref:`🔗` Returns whether or not the specified layer of the :ref:`collision_mask` is enabled, given a ``layer_number`` between 1 and 32. @@ -389,7 +389,7 @@ Returns whether or not the specified layer of the :ref:`collision_mask` **get_rid**\ (\ ) |const| +:ref:`RID` **get_rid**\ (\ ) |const| :ref:`🔗` Returns the object's :ref:`RID`. @@ -401,7 +401,7 @@ Returns the object's :ref:`RID`. .. rst-class:: classref-method -:ref:`PackedInt32Array` **get_shape_owners**\ (\ ) +:ref:`PackedInt32Array` **get_shape_owners**\ (\ ) :ref:`🔗` Returns an :ref:`Array` of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. @@ -413,7 +413,7 @@ Returns an :ref:`Array` of ``owner_id`` identifiers. You can use th .. rst-class:: classref-method -:ref:`bool` **is_shape_owner_disabled**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`bool` **is_shape_owner_disabled**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` If ``true``, the shape owner and its shapes are disabled. @@ -425,7 +425,7 @@ If ``true``, the shape owner and its shapes are disabled. .. rst-class:: classref-method -|void| **remove_shape_owner**\ (\ owner_id\: :ref:`int`\ ) +|void| **remove_shape_owner**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` Removes the given shape owner. @@ -437,7 +437,7 @@ Removes the given shape owner. .. rst-class:: classref-method -|void| **set_collision_layer_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) +|void| **set_collision_layer_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` Based on ``value``, enables or disables the specified layer in the :ref:`collision_layer`, given a ``layer_number`` between 1 and 32. @@ -449,7 +449,7 @@ Based on ``value``, enables or disables the specified layer in the :ref:`collisi .. rst-class:: classref-method -|void| **set_collision_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) +|void| **set_collision_mask_value**\ (\ layer_number\: :ref:`int`, value\: :ref:`bool`\ ) :ref:`🔗` Based on ``value``, enables or disables the specified layer in the :ref:`collision_mask`, given a ``layer_number`` between 1 and 32. @@ -461,7 +461,7 @@ Based on ``value``, enables or disables the specified layer in the :ref:`collisi .. rst-class:: classref-method -:ref:`int` **shape_find_owner**\ (\ shape_index\: :ref:`int`\ ) |const| +:ref:`int` **shape_find_owner**\ (\ shape_index\: :ref:`int`\ ) |const| :ref:`🔗` Returns the ``owner_id`` of the given shape. @@ -473,7 +473,7 @@ Returns the ``owner_id`` of the given shape. .. rst-class:: classref-method -|void| **shape_owner_add_shape**\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape3D`\ ) +|void| **shape_owner_add_shape**\ (\ owner_id\: :ref:`int`, shape\: :ref:`Shape3D`\ ) :ref:`🔗` Adds a :ref:`Shape3D` to the shape owner. @@ -485,7 +485,7 @@ Adds a :ref:`Shape3D` to the shape owner. .. rst-class:: classref-method -|void| **shape_owner_clear_shapes**\ (\ owner_id\: :ref:`int`\ ) +|void| **shape_owner_clear_shapes**\ (\ owner_id\: :ref:`int`\ ) :ref:`🔗` Removes all shapes from the shape owner. @@ -497,7 +497,7 @@ Removes all shapes from the shape owner. .. rst-class:: classref-method -:ref:`Object` **shape_owner_get_owner**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`Object` **shape_owner_get_owner**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the parent object of the given shape owner. @@ -509,7 +509,7 @@ Returns the parent object of the given shape owner. .. rst-class:: classref-method -:ref:`Shape3D` **shape_owner_get_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| +:ref:`Shape3D` **shape_owner_get_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the :ref:`Shape3D` with the given ID from the given shape owner. @@ -521,7 +521,7 @@ Returns the :ref:`Shape3D` with the given ID from the given shape .. rst-class:: classref-method -:ref:`int` **shape_owner_get_shape_count**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`int` **shape_owner_get_shape_count**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the number of shapes the given shape owner contains. @@ -533,7 +533,7 @@ Returns the number of shapes the given shape owner contains. .. rst-class:: classref-method -:ref:`int` **shape_owner_get_shape_index**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| +:ref:`int` **shape_owner_get_shape_index**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the child index of the :ref:`Shape3D` with the given ID from the given shape owner. @@ -545,7 +545,7 @@ Returns the child index of the :ref:`Shape3D` with the given ID f .. rst-class:: classref-method -:ref:`Transform3D` **shape_owner_get_transform**\ (\ owner_id\: :ref:`int`\ ) |const| +:ref:`Transform3D` **shape_owner_get_transform**\ (\ owner_id\: :ref:`int`\ ) |const| :ref:`🔗` Returns the shape owner's :ref:`Transform3D`. @@ -557,7 +557,7 @@ Returns the shape owner's :ref:`Transform3D`. .. rst-class:: classref-method -|void| **shape_owner_remove_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) +|void| **shape_owner_remove_shape**\ (\ owner_id\: :ref:`int`, shape_id\: :ref:`int`\ ) :ref:`🔗` Removes a shape from the given shape owner. @@ -569,7 +569,7 @@ Removes a shape from the given shape owner. .. rst-class:: classref-method -|void| **shape_owner_set_disabled**\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) +|void| **shape_owner_set_disabled**\ (\ owner_id\: :ref:`int`, disabled\: :ref:`bool`\ ) :ref:`🔗` If ``true``, disables the given shape owner. @@ -581,11 +581,12 @@ If ``true``, disables the given shape owner. .. rst-class:: classref-method -|void| **shape_owner_set_transform**\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform3D`\ ) +|void| **shape_owner_set_transform**\ (\ owner_id\: :ref:`int`, transform\: :ref:`Transform3D`\ ) :ref:`🔗` Sets the :ref:`Transform3D` of the given shape owner. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_collisionpolygon2d.rst b/classes/class_collisionpolygon2d.rst index 2d9fd9da366..a2c2a365cb5 100644 --- a/classes/class_collisionpolygon2d.rst +++ b/classes/class_collisionpolygon2d.rst @@ -19,9 +19,9 @@ A node that provides a polygon shape 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. +A node that provides a polygon shape 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`, turn :ref:`PhysicsBody2D` into a solid object, or give a hollow shape to a :ref:`StaticBody2D`. -\ **Warning:** A non-uniformly scaled :ref:`CollisionShape2D` will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead. +\ **Warning:** A non-uniformly scaled **CollisionPolygon2D** will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its polygon instead. .. rst-class:: classref-reftable-group @@ -56,7 +56,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **BuildMode**: +enum **BuildMode**: :ref:`🔗` .. _class_CollisionPolygon2D_constant_BUILD_SOLIDS: @@ -87,14 +87,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`BuildMode` **build_mode** = ``0`` +:ref:`BuildMode` **build_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_build_mode**\ (\ value\: :ref:`BuildMode`\ ) - :ref:`BuildMode` **get_build_mode**\ (\ ) -Collision build mode. Use one of the :ref:`BuildMode` constants. +Collision build mode. .. rst-class:: classref-item-separator @@ -104,14 +104,14 @@ Collision build mode. Use one of the :ref:`BuildMode` **disabled** = ``false`` +:ref:`bool` **disabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_disabled**\ (\ ) -If ``true``, no collisions will be detected. +If ``true``, no collisions will be detected. This property should be changed with :ref:`Object.set_deferred()`. .. rst-class:: classref-item-separator @@ -121,7 +121,7 @@ If ``true``, no collisions will be detected. .. rst-class:: classref-property -:ref:`bool` **one_way_collision** = ``false`` +:ref:`bool` **one_way_collision** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -140,7 +140,7 @@ If ``true``, only edges that face up, relative to **CollisionPolygon2D**'s rotat .. rst-class:: classref-property -:ref:`float` **one_way_collision_margin** = ``1.0`` +:ref:`float` **one_way_collision_margin** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -157,7 +157,7 @@ The margin used for one-way collision (in pixels). Higher values will make the s .. rst-class:: classref-property -:ref:`PackedVector2Array` **polygon** = ``PackedVector2Array()`` +:ref:`PackedVector2Array` **polygon** = ``PackedVector2Array()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -168,9 +168,10 @@ The polygon's list of vertices. Each point will be connected to the next, and th \ **Note:** The returned vertices are in the local coordinate space of the given **CollisionPolygon2D**. -\ **Warning:** The returned value is a clone of the :ref:`PackedVector2Array`, not a reference. +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector2Array` for more details. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_collisionpolygon3d.rst b/classes/class_collisionpolygon3d.rst index eaba73a5891..42caaaafc36 100644 --- a/classes/class_collisionpolygon3d.rst +++ b/classes/class_collisionpolygon3d.rst @@ -31,15 +31,19 @@ Properties .. table:: :widths: auto - +-----------------------------------------------------+-------------------------------------------------------------+--------------------------+ - | :ref:`float` | :ref:`depth` | ``1.0`` | - +-----------------------------------------------------+-------------------------------------------------------------+--------------------------+ - | :ref:`bool` | :ref:`disabled` | ``false`` | - +-----------------------------------------------------+-------------------------------------------------------------+--------------------------+ - | :ref:`float` | :ref:`margin` | ``0.04`` | - +-----------------------------------------------------+-------------------------------------------------------------+--------------------------+ - | :ref:`PackedVector2Array` | :ref:`polygon` | ``PackedVector2Array()`` | - +-----------------------------------------------------+-------------------------------------------------------------+--------------------------+ + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`debug_fill` | ``true`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`float` | :ref:`depth` | ``1.0`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`float` | :ref:`margin` | ``0.04`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ + | :ref:`PackedVector2Array` | :ref:`polygon` | ``PackedVector2Array()`` | + +-----------------------------------------------------+-------------------------------------------------------------------+--------------------------+ .. rst-class:: classref-section-separator @@ -50,11 +54,47 @@ Properties Property Descriptions --------------------- +.. _class_CollisionPolygon3D_property_debug_color: + +.. rst-class:: classref-property + +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionPolygon3D_property_debug_fill: + +.. rst-class:: classref-property + +:ref:`bool` **debug_fill** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_enable_debug_fill**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +.. rst-class:: classref-item-separator + +---- + .. _class_CollisionPolygon3D_property_depth: .. rst-class:: classref-property -:ref:`float` **depth** = ``1.0`` +:ref:`float` **depth** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -71,14 +111,14 @@ Length that the resulting collision extends in either direction perpendicular to .. rst-class:: classref-property -:ref:`bool` **disabled** = ``false`` +:ref:`bool` **disabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_disabled**\ (\ ) -If ``true``, no collision will be produced. +If ``true``, no collision will be produced. This property should be changed with :ref:`Object.set_deferred()`. .. rst-class:: classref-item-separator @@ -88,7 +128,7 @@ If ``true``, no collision will be produced. .. rst-class:: classref-property -:ref:`float` **margin** = ``0.04`` +:ref:`float` **margin** = ``0.04`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -105,7 +145,7 @@ The collision margin for the generated :ref:`Shape3D`. See :ref:` .. rst-class:: classref-property -:ref:`PackedVector2Array` **polygon** = ``PackedVector2Array()`` +:ref:`PackedVector2Array` **polygon** = ``PackedVector2Array()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -114,9 +154,10 @@ The collision margin for the generated :ref:`Shape3D`. See :ref:` Array of vertices which define the 2D polygon in the local XY plane. -\ **Note:** The returned value is a copy of the original. Methods which mutate the size or properties of the return value will not impact the original polygon. To change properties of the polygon, assign it to a temporary variable and make changes before reassigning the class property. +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector2Array` for more details. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_collisionshape2d.rst b/classes/class_collisionshape2d.rst index 47db055107c..8a790e3314e 100644 --- a/classes/class_collisionshape2d.rst +++ b/classes/class_collisionshape2d.rst @@ -28,11 +28,11 @@ Tutorials - :doc:`Physics introduction <../tutorials/physics/physics_introduction>` -- `2D Dodge The Creeps Demo `__ +- `2D Dodge The Creeps Demo `__ -- `2D Pong Demo `__ +- `2D Pong Demo `__ -- `2D Kinematic Character Demo `__ +- `2D Kinematic Character Demo `__ .. rst-class:: classref-reftable-group @@ -43,7 +43,7 @@ Properties :widths: auto +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ - | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 1)`` | + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`disabled` | ``false`` | +-------------------------------+-------------------------------------------------------------------------------------------+-----------------------+ @@ -67,16 +67,16 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Color` **debug_color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) - :ref:`Color` **get_debug_color**\ (\ ) -The collision shape debug color. +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. -\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 1)`` value documented here is a placeholder, and not the actual default debug color. +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. .. rst-class:: classref-item-separator @@ -86,14 +86,14 @@ The collision shape debug color. .. rst-class:: classref-property -:ref:`bool` **disabled** = ``false`` +:ref:`bool` **disabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_disabled**\ (\ ) -A disabled collision shape has no effect in the world. This property should be changed with :ref:`Object.set_deferred`. +A disabled collision shape has no effect in the world. This property should be changed with :ref:`Object.set_deferred()`. .. rst-class:: classref-item-separator @@ -103,7 +103,7 @@ A disabled collision shape has no effect in the world. This property should be c .. rst-class:: classref-property -:ref:`bool` **one_way_collision** = ``false`` +:ref:`bool` **one_way_collision** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -122,7 +122,7 @@ Sets whether this collision shape should only detect collision on one side (top .. rst-class:: classref-property -:ref:`float` **one_way_collision_margin** = ``1.0`` +:ref:`float` **one_way_collision_margin** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -139,7 +139,7 @@ The margin used for one-way collision (in pixels). Higher values will make the s .. rst-class:: classref-property -:ref:`Shape2D` **shape** +:ref:`Shape2D` **shape** :ref:`🔗` .. rst-class:: classref-property-setget @@ -149,6 +149,7 @@ The margin used for one-way collision (in pixels). Higher values will make the s The actual shape owned by this collision shape. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_collisionshape3d.rst b/classes/class_collisionshape3d.rst index 8c199da95ac..fd5726c14d7 100644 --- a/classes/class_collisionshape3d.rst +++ b/classes/class_collisionshape3d.rst @@ -30,11 +30,11 @@ Tutorials - :doc:`Physics introduction <../tutorials/physics/physics_introduction>` -- `3D Kinematic Character Demo `__ +- `3D Kinematic Character Demo `__ -- `3D Platformer Demo `__ +- `3D Platformer Demo `__ -- `Third Person Shooter Demo `__ +- `Third Person Shooter (TPS) Demo `__ .. rst-class:: classref-reftable-group @@ -44,11 +44,15 @@ Properties .. table:: :widths: auto - +-------------------------------+-----------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`disabled` | ``false`` | - +-------------------------------+-----------------------------------------------------------+-----------+ - | :ref:`Shape3D` | :ref:`shape` | | - +-------------------------------+-----------------------------------------------------------+-----------+ + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`debug_fill` | ``true`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`Shape3D` | :ref:`shape` | | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ .. rst-class:: classref-reftable-group @@ -73,18 +77,54 @@ Methods Property Descriptions --------------------- +.. _class_CollisionShape3D_property_debug_color: + +.. rst-class:: classref-property + +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is :ref:`ProjectSettings.debug/shapes/collision/shape_color`. The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionShape3D_property_debug_fill: + +.. rst-class:: classref-property + +:ref:`bool` **debug_fill** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_enable_debug_fill**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +.. rst-class:: classref-item-separator + +---- + .. _class_CollisionShape3D_property_disabled: .. rst-class:: classref-property -:ref:`bool` **disabled** = ``false`` +:ref:`bool` **disabled** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_disabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_disabled**\ (\ ) -A disabled collision shape has no effect in the world. +A disabled collision shape has no effect in the world. This property should be changed with :ref:`Object.set_deferred()`. .. rst-class:: classref-item-separator @@ -94,7 +134,7 @@ A disabled collision shape has no effect in the world. .. rst-class:: classref-property -:ref:`Shape3D` **shape** +:ref:`Shape3D` **shape** :ref:`🔗` .. rst-class:: classref-property-setget @@ -116,7 +156,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **make_convex_from_siblings**\ (\ ) +|void| **make_convex_from_siblings**\ (\ ) :ref:`🔗` Sets the collision shape's shape to the addition of all its convexed :ref:`MeshInstance3D` siblings geometry. @@ -128,13 +168,14 @@ Sets the collision shape's shape to the addition of all its convexed :ref:`MeshI .. rst-class:: classref-method -|void| **resource_changed**\ (\ resource\: :ref:`Resource`\ ) +|void| **resource_changed**\ (\ resource\: :ref:`Resource`\ ) :ref:`🔗` **Deprecated:** Use :ref:`Resource.changed` instead. This method does nothing. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_color.rst b/classes/class_color.rst index ab3fd2977e8..41af72a4cbb 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -19,7 +19,9 @@ Description 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 32-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 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. +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. + +Color data may be stored in many color spaces and encodings. The :ref:`srgb_to_linear()` and :ref:`linear_to_srgb()` methods can convert between nonlinear sRGB encoding and linear RGB encoding. \ **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``. @@ -34,11 +36,11 @@ Colors can be created in various ways: By the various **Color** constructors, by Tutorials --------- -- `2D GD Paint Demo `__ +- `2D GD Paint Demo `__ -- `Tween Demo `__ +- `Tween Interpolation Demo `__ -- `GUI Drag And Drop Demo `__ +- `GUI Drag And Drop Demo `__ .. rst-class:: classref-reftable-group @@ -48,29 +50,35 @@ Properties .. table:: :widths: auto - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`a` | ``1.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`a8` | ``255`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`b` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`b8` | ``0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`g` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`g8` | ``0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`h` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`r` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`r8` | ``0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`s` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`v` | ``0.0`` | - +---------------------------+------------------------------------+---------+ + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`a` | ``1.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`a8` | ``255`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`b` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`b8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`g` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`g8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`h` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_h` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_l` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_s` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`r` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`r8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`s` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`v` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ .. rst-class:: classref-reftable-group @@ -115,6 +123,8 @@ Methods +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`from_ok_hsl`\ (\ h\: :ref:`float`, s\: :ref:`float`, l\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| | +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`from_rgba8`\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) |static| | + +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`from_rgbe9995`\ (\ rgbe\: :ref:`int`\ ) |static| | +-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`from_string`\ (\ str\: :ref:`String`, default\: :ref:`Color`\ ) |static| | @@ -205,7 +215,7 @@ Constants .. rst-class:: classref-constant -**ALICE_BLUE** = ``Color(0.941176, 0.972549, 1, 1)`` +**ALICE_BLUE** = ``Color(0.9411765, 0.972549, 1, 1)`` :ref:`🔗` Alice blue color. @@ -213,7 +223,7 @@ Alice blue color. .. rst-class:: classref-constant -**ANTIQUE_WHITE** = ``Color(0.980392, 0.921569, 0.843137, 1)`` +**ANTIQUE_WHITE** = ``Color(0.98039216, 0.92156863, 0.84313726, 1)`` :ref:`🔗` Antique white color. @@ -221,7 +231,7 @@ Antique white color. .. rst-class:: classref-constant -**AQUA** = ``Color(0, 1, 1, 1)`` +**AQUA** = ``Color(0, 1, 1, 1)`` :ref:`🔗` Aqua color. @@ -229,7 +239,7 @@ Aqua color. .. rst-class:: classref-constant -**AQUAMARINE** = ``Color(0.498039, 1, 0.831373, 1)`` +**AQUAMARINE** = ``Color(0.49803922, 1, 0.83137256, 1)`` :ref:`🔗` Aquamarine color. @@ -237,7 +247,7 @@ Aquamarine color. .. rst-class:: classref-constant -**AZURE** = ``Color(0.941176, 1, 1, 1)`` +**AZURE** = ``Color(0.9411765, 1, 1, 1)`` :ref:`🔗` Azure color. @@ -245,7 +255,7 @@ Azure color. .. rst-class:: classref-constant -**BEIGE** = ``Color(0.960784, 0.960784, 0.862745, 1)`` +**BEIGE** = ``Color(0.9607843, 0.9607843, 0.8627451, 1)`` :ref:`🔗` Beige color. @@ -253,7 +263,7 @@ Beige color. .. rst-class:: classref-constant -**BISQUE** = ``Color(1, 0.894118, 0.768627, 1)`` +**BISQUE** = ``Color(1, 0.89411765, 0.76862746, 1)`` :ref:`🔗` Bisque color. @@ -261,7 +271,7 @@ Bisque color. .. rst-class:: classref-constant -**BLACK** = ``Color(0, 0, 0, 1)`` +**BLACK** = ``Color(0, 0, 0, 1)`` :ref:`🔗` Black color. In GDScript, this is the default value of any color. @@ -269,7 +279,7 @@ Black color. In GDScript, this is the default value of any color. .. rst-class:: classref-constant -**BLANCHED_ALMOND** = ``Color(1, 0.921569, 0.803922, 1)`` +**BLANCHED_ALMOND** = ``Color(1, 0.92156863, 0.8039216, 1)`` :ref:`🔗` Blanched almond color. @@ -277,7 +287,7 @@ Blanched almond color. .. rst-class:: classref-constant -**BLUE** = ``Color(0, 0, 1, 1)`` +**BLUE** = ``Color(0, 0, 1, 1)`` :ref:`🔗` Blue color. @@ -285,7 +295,7 @@ Blue color. .. rst-class:: classref-constant -**BLUE_VIOLET** = ``Color(0.541176, 0.168627, 0.886275, 1)`` +**BLUE_VIOLET** = ``Color(0.5411765, 0.16862746, 0.8862745, 1)`` :ref:`🔗` Blue violet color. @@ -293,7 +303,7 @@ Blue violet color. .. rst-class:: classref-constant -**BROWN** = ``Color(0.647059, 0.164706, 0.164706, 1)`` +**BROWN** = ``Color(0.64705884, 0.16470589, 0.16470589, 1)`` :ref:`🔗` Brown color. @@ -301,7 +311,7 @@ Brown color. .. rst-class:: classref-constant -**BURLYWOOD** = ``Color(0.870588, 0.721569, 0.529412, 1)`` +**BURLYWOOD** = ``Color(0.87058824, 0.72156864, 0.5294118, 1)`` :ref:`🔗` Burlywood color. @@ -309,7 +319,7 @@ Burlywood color. .. rst-class:: classref-constant -**CADET_BLUE** = ``Color(0.372549, 0.619608, 0.627451, 1)`` +**CADET_BLUE** = ``Color(0.37254903, 0.61960787, 0.627451, 1)`` :ref:`🔗` Cadet blue color. @@ -317,7 +327,7 @@ Cadet blue color. .. rst-class:: classref-constant -**CHARTREUSE** = ``Color(0.498039, 1, 0, 1)`` +**CHARTREUSE** = ``Color(0.49803922, 1, 0, 1)`` :ref:`🔗` Chartreuse color. @@ -325,7 +335,7 @@ Chartreuse color. .. rst-class:: classref-constant -**CHOCOLATE** = ``Color(0.823529, 0.411765, 0.117647, 1)`` +**CHOCOLATE** = ``Color(0.8235294, 0.4117647, 0.11764706, 1)`` :ref:`🔗` Chocolate color. @@ -333,7 +343,7 @@ Chocolate color. .. rst-class:: classref-constant -**CORAL** = ``Color(1, 0.498039, 0.313726, 1)`` +**CORAL** = ``Color(1, 0.49803922, 0.3137255, 1)`` :ref:`🔗` Coral color. @@ -341,7 +351,7 @@ Coral color. .. rst-class:: classref-constant -**CORNFLOWER_BLUE** = ``Color(0.392157, 0.584314, 0.929412, 1)`` +**CORNFLOWER_BLUE** = ``Color(0.39215687, 0.58431375, 0.92941177, 1)`` :ref:`🔗` Cornflower blue color. @@ -349,7 +359,7 @@ Cornflower blue color. .. rst-class:: classref-constant -**CORNSILK** = ``Color(1, 0.972549, 0.862745, 1)`` +**CORNSILK** = ``Color(1, 0.972549, 0.8627451, 1)`` :ref:`🔗` Cornsilk color. @@ -357,7 +367,7 @@ Cornsilk color. .. rst-class:: classref-constant -**CRIMSON** = ``Color(0.862745, 0.0784314, 0.235294, 1)`` +**CRIMSON** = ``Color(0.8627451, 0.078431375, 0.23529412, 1)`` :ref:`🔗` Crimson color. @@ -365,7 +375,7 @@ Crimson color. .. rst-class:: classref-constant -**CYAN** = ``Color(0, 1, 1, 1)`` +**CYAN** = ``Color(0, 1, 1, 1)`` :ref:`🔗` Cyan color. @@ -373,7 +383,7 @@ Cyan color. .. rst-class:: classref-constant -**DARK_BLUE** = ``Color(0, 0, 0.545098, 1)`` +**DARK_BLUE** = ``Color(0, 0, 0.54509807, 1)`` :ref:`🔗` Dark blue color. @@ -381,7 +391,7 @@ Dark blue color. .. rst-class:: classref-constant -**DARK_CYAN** = ``Color(0, 0.545098, 0.545098, 1)`` +**DARK_CYAN** = ``Color(0, 0.54509807, 0.54509807, 1)`` :ref:`🔗` Dark cyan color. @@ -389,7 +399,7 @@ Dark cyan color. .. rst-class:: classref-constant -**DARK_GOLDENROD** = ``Color(0.721569, 0.52549, 0.0431373, 1)`` +**DARK_GOLDENROD** = ``Color(0.72156864, 0.5254902, 0.043137256, 1)`` :ref:`🔗` Dark goldenrod color. @@ -397,7 +407,7 @@ Dark goldenrod color. .. rst-class:: classref-constant -**DARK_GRAY** = ``Color(0.662745, 0.662745, 0.662745, 1)`` +**DARK_GRAY** = ``Color(0.6627451, 0.6627451, 0.6627451, 1)`` :ref:`🔗` Dark gray color. @@ -405,7 +415,7 @@ Dark gray color. .. rst-class:: classref-constant -**DARK_GREEN** = ``Color(0, 0.392157, 0, 1)`` +**DARK_GREEN** = ``Color(0, 0.39215687, 0, 1)`` :ref:`🔗` Dark green color. @@ -413,7 +423,7 @@ Dark green color. .. rst-class:: classref-constant -**DARK_KHAKI** = ``Color(0.741176, 0.717647, 0.419608, 1)`` +**DARK_KHAKI** = ``Color(0.7411765, 0.7176471, 0.41960785, 1)`` :ref:`🔗` Dark khaki color. @@ -421,7 +431,7 @@ Dark khaki color. .. rst-class:: classref-constant -**DARK_MAGENTA** = ``Color(0.545098, 0, 0.545098, 1)`` +**DARK_MAGENTA** = ``Color(0.54509807, 0, 0.54509807, 1)`` :ref:`🔗` Dark magenta color. @@ -429,7 +439,7 @@ Dark magenta color. .. rst-class:: classref-constant -**DARK_OLIVE_GREEN** = ``Color(0.333333, 0.419608, 0.184314, 1)`` +**DARK_OLIVE_GREEN** = ``Color(0.33333334, 0.41960785, 0.18431373, 1)`` :ref:`🔗` Dark olive green color. @@ -437,7 +447,7 @@ Dark olive green color. .. rst-class:: classref-constant -**DARK_ORANGE** = ``Color(1, 0.54902, 0, 1)`` +**DARK_ORANGE** = ``Color(1, 0.54901963, 0, 1)`` :ref:`🔗` Dark orange color. @@ -445,7 +455,7 @@ Dark orange color. .. rst-class:: classref-constant -**DARK_ORCHID** = ``Color(0.6, 0.196078, 0.8, 1)`` +**DARK_ORCHID** = ``Color(0.6, 0.19607843, 0.8, 1)`` :ref:`🔗` Dark orchid color. @@ -453,7 +463,7 @@ Dark orchid color. .. rst-class:: classref-constant -**DARK_RED** = ``Color(0.545098, 0, 0, 1)`` +**DARK_RED** = ``Color(0.54509807, 0, 0, 1)`` :ref:`🔗` Dark red color. @@ -461,7 +471,7 @@ Dark red color. .. rst-class:: classref-constant -**DARK_SALMON** = ``Color(0.913725, 0.588235, 0.478431, 1)`` +**DARK_SALMON** = ``Color(0.9137255, 0.5882353, 0.47843137, 1)`` :ref:`🔗` Dark salmon color. @@ -469,7 +479,7 @@ Dark salmon color. .. rst-class:: classref-constant -**DARK_SEA_GREEN** = ``Color(0.560784, 0.737255, 0.560784, 1)`` +**DARK_SEA_GREEN** = ``Color(0.56078434, 0.7372549, 0.56078434, 1)`` :ref:`🔗` Dark sea green color. @@ -477,7 +487,7 @@ Dark sea green color. .. rst-class:: classref-constant -**DARK_SLATE_BLUE** = ``Color(0.282353, 0.239216, 0.545098, 1)`` +**DARK_SLATE_BLUE** = ``Color(0.28235295, 0.23921569, 0.54509807, 1)`` :ref:`🔗` Dark slate blue color. @@ -485,7 +495,7 @@ Dark slate blue color. .. rst-class:: classref-constant -**DARK_SLATE_GRAY** = ``Color(0.184314, 0.309804, 0.309804, 1)`` +**DARK_SLATE_GRAY** = ``Color(0.18431373, 0.30980393, 0.30980393, 1)`` :ref:`🔗` Dark slate gray color. @@ -493,7 +503,7 @@ Dark slate gray color. .. rst-class:: classref-constant -**DARK_TURQUOISE** = ``Color(0, 0.807843, 0.819608, 1)`` +**DARK_TURQUOISE** = ``Color(0, 0.80784315, 0.81960785, 1)`` :ref:`🔗` Dark turquoise color. @@ -501,7 +511,7 @@ Dark turquoise color. .. rst-class:: classref-constant -**DARK_VIOLET** = ``Color(0.580392, 0, 0.827451, 1)`` +**DARK_VIOLET** = ``Color(0.5803922, 0, 0.827451, 1)`` :ref:`🔗` Dark violet color. @@ -509,7 +519,7 @@ Dark violet color. .. rst-class:: classref-constant -**DEEP_PINK** = ``Color(1, 0.0784314, 0.576471, 1)`` +**DEEP_PINK** = ``Color(1, 0.078431375, 0.5764706, 1)`` :ref:`🔗` Deep pink color. @@ -517,7 +527,7 @@ Deep pink color. .. rst-class:: classref-constant -**DEEP_SKY_BLUE** = ``Color(0, 0.74902, 1, 1)`` +**DEEP_SKY_BLUE** = ``Color(0, 0.7490196, 1, 1)`` :ref:`🔗` Deep sky blue color. @@ -525,7 +535,7 @@ Deep sky blue color. .. rst-class:: classref-constant -**DIM_GRAY** = ``Color(0.411765, 0.411765, 0.411765, 1)`` +**DIM_GRAY** = ``Color(0.4117647, 0.4117647, 0.4117647, 1)`` :ref:`🔗` Dim gray color. @@ -533,7 +543,7 @@ Dim gray color. .. rst-class:: classref-constant -**DODGER_BLUE** = ``Color(0.117647, 0.564706, 1, 1)`` +**DODGER_BLUE** = ``Color(0.11764706, 0.5647059, 1, 1)`` :ref:`🔗` Dodger blue color. @@ -541,7 +551,7 @@ Dodger blue color. .. rst-class:: classref-constant -**FIREBRICK** = ``Color(0.698039, 0.133333, 0.133333, 1)`` +**FIREBRICK** = ``Color(0.69803923, 0.13333334, 0.13333334, 1)`` :ref:`🔗` Firebrick color. @@ -549,7 +559,7 @@ Firebrick color. .. rst-class:: classref-constant -**FLORAL_WHITE** = ``Color(1, 0.980392, 0.941176, 1)`` +**FLORAL_WHITE** = ``Color(1, 0.98039216, 0.9411765, 1)`` :ref:`🔗` Floral white color. @@ -557,7 +567,7 @@ Floral white color. .. rst-class:: classref-constant -**FOREST_GREEN** = ``Color(0.133333, 0.545098, 0.133333, 1)`` +**FOREST_GREEN** = ``Color(0.13333334, 0.54509807, 0.13333334, 1)`` :ref:`🔗` Forest green color. @@ -565,7 +575,7 @@ Forest green color. .. rst-class:: classref-constant -**FUCHSIA** = ``Color(1, 0, 1, 1)`` +**FUCHSIA** = ``Color(1, 0, 1, 1)`` :ref:`🔗` Fuchsia color. @@ -573,7 +583,7 @@ Fuchsia color. .. rst-class:: classref-constant -**GAINSBORO** = ``Color(0.862745, 0.862745, 0.862745, 1)`` +**GAINSBORO** = ``Color(0.8627451, 0.8627451, 0.8627451, 1)`` :ref:`🔗` Gainsboro color. @@ -581,7 +591,7 @@ Gainsboro color. .. rst-class:: classref-constant -**GHOST_WHITE** = ``Color(0.972549, 0.972549, 1, 1)`` +**GHOST_WHITE** = ``Color(0.972549, 0.972549, 1, 1)`` :ref:`🔗` Ghost white color. @@ -589,7 +599,7 @@ Ghost white color. .. rst-class:: classref-constant -**GOLD** = ``Color(1, 0.843137, 0, 1)`` +**GOLD** = ``Color(1, 0.84313726, 0, 1)`` :ref:`🔗` Gold color. @@ -597,7 +607,7 @@ Gold color. .. rst-class:: classref-constant -**GOLDENROD** = ``Color(0.854902, 0.647059, 0.12549, 1)`` +**GOLDENROD** = ``Color(0.85490197, 0.64705884, 0.1254902, 1)`` :ref:`🔗` Goldenrod color. @@ -605,7 +615,7 @@ Goldenrod color. .. rst-class:: classref-constant -**GRAY** = ``Color(0.745098, 0.745098, 0.745098, 1)`` +**GRAY** = ``Color(0.74509805, 0.74509805, 0.74509805, 1)`` :ref:`🔗` Gray color. @@ -613,7 +623,7 @@ Gray color. .. rst-class:: classref-constant -**GREEN** = ``Color(0, 1, 0, 1)`` +**GREEN** = ``Color(0, 1, 0, 1)`` :ref:`🔗` Green color. @@ -621,7 +631,7 @@ Green color. .. rst-class:: classref-constant -**GREEN_YELLOW** = ``Color(0.678431, 1, 0.184314, 1)`` +**GREEN_YELLOW** = ``Color(0.6784314, 1, 0.18431373, 1)`` :ref:`🔗` Green yellow color. @@ -629,7 +639,7 @@ Green yellow color. .. rst-class:: classref-constant -**HONEYDEW** = ``Color(0.941176, 1, 0.941176, 1)`` +**HONEYDEW** = ``Color(0.9411765, 1, 0.9411765, 1)`` :ref:`🔗` Honeydew color. @@ -637,7 +647,7 @@ Honeydew color. .. rst-class:: classref-constant -**HOT_PINK** = ``Color(1, 0.411765, 0.705882, 1)`` +**HOT_PINK** = ``Color(1, 0.4117647, 0.7058824, 1)`` :ref:`🔗` Hot pink color. @@ -645,7 +655,7 @@ Hot pink color. .. rst-class:: classref-constant -**INDIAN_RED** = ``Color(0.803922, 0.360784, 0.360784, 1)`` +**INDIAN_RED** = ``Color(0.8039216, 0.36078432, 0.36078432, 1)`` :ref:`🔗` Indian red color. @@ -653,7 +663,7 @@ Indian red color. .. rst-class:: classref-constant -**INDIGO** = ``Color(0.294118, 0, 0.509804, 1)`` +**INDIGO** = ``Color(0.29411766, 0, 0.50980395, 1)`` :ref:`🔗` Indigo color. @@ -661,7 +671,7 @@ Indigo color. .. rst-class:: classref-constant -**IVORY** = ``Color(1, 1, 0.941176, 1)`` +**IVORY** = ``Color(1, 1, 0.9411765, 1)`` :ref:`🔗` Ivory color. @@ -669,7 +679,7 @@ Ivory color. .. rst-class:: classref-constant -**KHAKI** = ``Color(0.941176, 0.901961, 0.54902, 1)`` +**KHAKI** = ``Color(0.9411765, 0.9019608, 0.54901963, 1)`` :ref:`🔗` Khaki color. @@ -677,7 +687,7 @@ Khaki color. .. rst-class:: classref-constant -**LAVENDER** = ``Color(0.901961, 0.901961, 0.980392, 1)`` +**LAVENDER** = ``Color(0.9019608, 0.9019608, 0.98039216, 1)`` :ref:`🔗` Lavender color. @@ -685,7 +695,7 @@ Lavender color. .. rst-class:: classref-constant -**LAVENDER_BLUSH** = ``Color(1, 0.941176, 0.960784, 1)`` +**LAVENDER_BLUSH** = ``Color(1, 0.9411765, 0.9607843, 1)`` :ref:`🔗` Lavender blush color. @@ -693,7 +703,7 @@ Lavender blush color. .. rst-class:: classref-constant -**LAWN_GREEN** = ``Color(0.486275, 0.988235, 0, 1)`` +**LAWN_GREEN** = ``Color(0.4862745, 0.9882353, 0, 1)`` :ref:`🔗` Lawn green color. @@ -701,7 +711,7 @@ Lawn green color. .. rst-class:: classref-constant -**LEMON_CHIFFON** = ``Color(1, 0.980392, 0.803922, 1)`` +**LEMON_CHIFFON** = ``Color(1, 0.98039216, 0.8039216, 1)`` :ref:`🔗` Lemon chiffon color. @@ -709,7 +719,7 @@ Lemon chiffon color. .. rst-class:: classref-constant -**LIGHT_BLUE** = ``Color(0.678431, 0.847059, 0.901961, 1)`` +**LIGHT_BLUE** = ``Color(0.6784314, 0.84705883, 0.9019608, 1)`` :ref:`🔗` Light blue color. @@ -717,7 +727,7 @@ Light blue color. .. rst-class:: classref-constant -**LIGHT_CORAL** = ``Color(0.941176, 0.501961, 0.501961, 1)`` +**LIGHT_CORAL** = ``Color(0.9411765, 0.5019608, 0.5019608, 1)`` :ref:`🔗` Light coral color. @@ -725,7 +735,7 @@ Light coral color. .. rst-class:: classref-constant -**LIGHT_CYAN** = ``Color(0.878431, 1, 1, 1)`` +**LIGHT_CYAN** = ``Color(0.8784314, 1, 1, 1)`` :ref:`🔗` Light cyan color. @@ -733,7 +743,7 @@ Light cyan color. .. rst-class:: classref-constant -**LIGHT_GOLDENROD** = ``Color(0.980392, 0.980392, 0.823529, 1)`` +**LIGHT_GOLDENROD** = ``Color(0.98039216, 0.98039216, 0.8235294, 1)`` :ref:`🔗` Light goldenrod color. @@ -741,7 +751,7 @@ Light goldenrod color. .. rst-class:: classref-constant -**LIGHT_GRAY** = ``Color(0.827451, 0.827451, 0.827451, 1)`` +**LIGHT_GRAY** = ``Color(0.827451, 0.827451, 0.827451, 1)`` :ref:`🔗` Light gray color. @@ -749,7 +759,7 @@ Light gray color. .. rst-class:: classref-constant -**LIGHT_GREEN** = ``Color(0.564706, 0.933333, 0.564706, 1)`` +**LIGHT_GREEN** = ``Color(0.5647059, 0.93333334, 0.5647059, 1)`` :ref:`🔗` Light green color. @@ -757,7 +767,7 @@ Light green color. .. rst-class:: classref-constant -**LIGHT_PINK** = ``Color(1, 0.713726, 0.756863, 1)`` +**LIGHT_PINK** = ``Color(1, 0.7137255, 0.75686276, 1)`` :ref:`🔗` Light pink color. @@ -765,7 +775,7 @@ Light pink color. .. rst-class:: classref-constant -**LIGHT_SALMON** = ``Color(1, 0.627451, 0.478431, 1)`` +**LIGHT_SALMON** = ``Color(1, 0.627451, 0.47843137, 1)`` :ref:`🔗` Light salmon color. @@ -773,7 +783,7 @@ Light salmon color. .. rst-class:: classref-constant -**LIGHT_SEA_GREEN** = ``Color(0.12549, 0.698039, 0.666667, 1)`` +**LIGHT_SEA_GREEN** = ``Color(0.1254902, 0.69803923, 0.6666667, 1)`` :ref:`🔗` Light sea green color. @@ -781,7 +791,7 @@ Light sea green color. .. rst-class:: classref-constant -**LIGHT_SKY_BLUE** = ``Color(0.529412, 0.807843, 0.980392, 1)`` +**LIGHT_SKY_BLUE** = ``Color(0.5294118, 0.80784315, 0.98039216, 1)`` :ref:`🔗` Light sky blue color. @@ -789,7 +799,7 @@ Light sky blue color. .. rst-class:: classref-constant -**LIGHT_SLATE_GRAY** = ``Color(0.466667, 0.533333, 0.6, 1)`` +**LIGHT_SLATE_GRAY** = ``Color(0.46666667, 0.53333336, 0.6, 1)`` :ref:`🔗` Light slate gray color. @@ -797,7 +807,7 @@ Light slate gray color. .. rst-class:: classref-constant -**LIGHT_STEEL_BLUE** = ``Color(0.690196, 0.768627, 0.870588, 1)`` +**LIGHT_STEEL_BLUE** = ``Color(0.6901961, 0.76862746, 0.87058824, 1)`` :ref:`🔗` Light steel blue color. @@ -805,7 +815,7 @@ Light steel blue color. .. rst-class:: classref-constant -**LIGHT_YELLOW** = ``Color(1, 1, 0.878431, 1)`` +**LIGHT_YELLOW** = ``Color(1, 1, 0.8784314, 1)`` :ref:`🔗` Light yellow color. @@ -813,7 +823,7 @@ Light yellow color. .. rst-class:: classref-constant -**LIME** = ``Color(0, 1, 0, 1)`` +**LIME** = ``Color(0, 1, 0, 1)`` :ref:`🔗` Lime color. @@ -821,7 +831,7 @@ Lime color. .. rst-class:: classref-constant -**LIME_GREEN** = ``Color(0.196078, 0.803922, 0.196078, 1)`` +**LIME_GREEN** = ``Color(0.19607843, 0.8039216, 0.19607843, 1)`` :ref:`🔗` Lime green color. @@ -829,7 +839,7 @@ Lime green color. .. rst-class:: classref-constant -**LINEN** = ``Color(0.980392, 0.941176, 0.901961, 1)`` +**LINEN** = ``Color(0.98039216, 0.9411765, 0.9019608, 1)`` :ref:`🔗` Linen color. @@ -837,7 +847,7 @@ Linen color. .. rst-class:: classref-constant -**MAGENTA** = ``Color(1, 0, 1, 1)`` +**MAGENTA** = ``Color(1, 0, 1, 1)`` :ref:`🔗` Magenta color. @@ -845,7 +855,7 @@ Magenta color. .. rst-class:: classref-constant -**MAROON** = ``Color(0.690196, 0.188235, 0.376471, 1)`` +**MAROON** = ``Color(0.6901961, 0.1882353, 0.3764706, 1)`` :ref:`🔗` Maroon color. @@ -853,7 +863,7 @@ Maroon color. .. rst-class:: classref-constant -**MEDIUM_AQUAMARINE** = ``Color(0.4, 0.803922, 0.666667, 1)`` +**MEDIUM_AQUAMARINE** = ``Color(0.4, 0.8039216, 0.6666667, 1)`` :ref:`🔗` Medium aquamarine color. @@ -861,7 +871,7 @@ Medium aquamarine color. .. rst-class:: classref-constant -**MEDIUM_BLUE** = ``Color(0, 0, 0.803922, 1)`` +**MEDIUM_BLUE** = ``Color(0, 0, 0.8039216, 1)`` :ref:`🔗` Medium blue color. @@ -869,7 +879,7 @@ Medium blue color. .. rst-class:: classref-constant -**MEDIUM_ORCHID** = ``Color(0.729412, 0.333333, 0.827451, 1)`` +**MEDIUM_ORCHID** = ``Color(0.7294118, 0.33333334, 0.827451, 1)`` :ref:`🔗` Medium orchid color. @@ -877,7 +887,7 @@ Medium orchid color. .. rst-class:: classref-constant -**MEDIUM_PURPLE** = ``Color(0.576471, 0.439216, 0.858824, 1)`` +**MEDIUM_PURPLE** = ``Color(0.5764706, 0.4392157, 0.85882354, 1)`` :ref:`🔗` Medium purple color. @@ -885,7 +895,7 @@ Medium purple color. .. rst-class:: classref-constant -**MEDIUM_SEA_GREEN** = ``Color(0.235294, 0.701961, 0.443137, 1)`` +**MEDIUM_SEA_GREEN** = ``Color(0.23529412, 0.7019608, 0.44313726, 1)`` :ref:`🔗` Medium sea green color. @@ -893,7 +903,7 @@ Medium sea green color. .. rst-class:: classref-constant -**MEDIUM_SLATE_BLUE** = ``Color(0.482353, 0.407843, 0.933333, 1)`` +**MEDIUM_SLATE_BLUE** = ``Color(0.48235294, 0.40784314, 0.93333334, 1)`` :ref:`🔗` Medium slate blue color. @@ -901,7 +911,7 @@ Medium slate blue color. .. rst-class:: classref-constant -**MEDIUM_SPRING_GREEN** = ``Color(0, 0.980392, 0.603922, 1)`` +**MEDIUM_SPRING_GREEN** = ``Color(0, 0.98039216, 0.6039216, 1)`` :ref:`🔗` Medium spring green color. @@ -909,7 +919,7 @@ Medium spring green color. .. rst-class:: classref-constant -**MEDIUM_TURQUOISE** = ``Color(0.282353, 0.819608, 0.8, 1)`` +**MEDIUM_TURQUOISE** = ``Color(0.28235295, 0.81960785, 0.8, 1)`` :ref:`🔗` Medium turquoise color. @@ -917,7 +927,7 @@ Medium turquoise color. .. rst-class:: classref-constant -**MEDIUM_VIOLET_RED** = ``Color(0.780392, 0.0823529, 0.521569, 1)`` +**MEDIUM_VIOLET_RED** = ``Color(0.78039217, 0.08235294, 0.52156866, 1)`` :ref:`🔗` Medium violet red color. @@ -925,7 +935,7 @@ Medium violet red color. .. rst-class:: classref-constant -**MIDNIGHT_BLUE** = ``Color(0.0980392, 0.0980392, 0.439216, 1)`` +**MIDNIGHT_BLUE** = ``Color(0.09803922, 0.09803922, 0.4392157, 1)`` :ref:`🔗` Midnight blue color. @@ -933,7 +943,7 @@ Midnight blue color. .. rst-class:: classref-constant -**MINT_CREAM** = ``Color(0.960784, 1, 0.980392, 1)`` +**MINT_CREAM** = ``Color(0.9607843, 1, 0.98039216, 1)`` :ref:`🔗` Mint cream color. @@ -941,7 +951,7 @@ Mint cream color. .. rst-class:: classref-constant -**MISTY_ROSE** = ``Color(1, 0.894118, 0.882353, 1)`` +**MISTY_ROSE** = ``Color(1, 0.89411765, 0.88235295, 1)`` :ref:`🔗` Misty rose color. @@ -949,7 +959,7 @@ Misty rose color. .. rst-class:: classref-constant -**MOCCASIN** = ``Color(1, 0.894118, 0.709804, 1)`` +**MOCCASIN** = ``Color(1, 0.89411765, 0.70980394, 1)`` :ref:`🔗` Moccasin color. @@ -957,7 +967,7 @@ Moccasin color. .. rst-class:: classref-constant -**NAVAJO_WHITE** = ``Color(1, 0.870588, 0.678431, 1)`` +**NAVAJO_WHITE** = ``Color(1, 0.87058824, 0.6784314, 1)`` :ref:`🔗` Navajo white color. @@ -965,7 +975,7 @@ Navajo white color. .. rst-class:: classref-constant -**NAVY_BLUE** = ``Color(0, 0, 0.501961, 1)`` +**NAVY_BLUE** = ``Color(0, 0, 0.5019608, 1)`` :ref:`🔗` Navy blue color. @@ -973,7 +983,7 @@ Navy blue color. .. rst-class:: classref-constant -**OLD_LACE** = ``Color(0.992157, 0.960784, 0.901961, 1)`` +**OLD_LACE** = ``Color(0.99215686, 0.9607843, 0.9019608, 1)`` :ref:`🔗` Old lace color. @@ -981,7 +991,7 @@ Old lace color. .. rst-class:: classref-constant -**OLIVE** = ``Color(0.501961, 0.501961, 0, 1)`` +**OLIVE** = ``Color(0.5019608, 0.5019608, 0, 1)`` :ref:`🔗` Olive color. @@ -989,7 +999,7 @@ Olive color. .. rst-class:: classref-constant -**OLIVE_DRAB** = ``Color(0.419608, 0.556863, 0.137255, 1)`` +**OLIVE_DRAB** = ``Color(0.41960785, 0.5568628, 0.13725491, 1)`` :ref:`🔗` Olive drab color. @@ -997,7 +1007,7 @@ Olive drab color. .. rst-class:: classref-constant -**ORANGE** = ``Color(1, 0.647059, 0, 1)`` +**ORANGE** = ``Color(1, 0.64705884, 0, 1)`` :ref:`🔗` Orange color. @@ -1005,7 +1015,7 @@ Orange color. .. rst-class:: classref-constant -**ORANGE_RED** = ``Color(1, 0.270588, 0, 1)`` +**ORANGE_RED** = ``Color(1, 0.27058825, 0, 1)`` :ref:`🔗` Orange red color. @@ -1013,7 +1023,7 @@ Orange red color. .. rst-class:: classref-constant -**ORCHID** = ``Color(0.854902, 0.439216, 0.839216, 1)`` +**ORCHID** = ``Color(0.85490197, 0.4392157, 0.8392157, 1)`` :ref:`🔗` Orchid color. @@ -1021,7 +1031,7 @@ Orchid color. .. rst-class:: classref-constant -**PALE_GOLDENROD** = ``Color(0.933333, 0.909804, 0.666667, 1)`` +**PALE_GOLDENROD** = ``Color(0.93333334, 0.9098039, 0.6666667, 1)`` :ref:`🔗` Pale goldenrod color. @@ -1029,7 +1039,7 @@ Pale goldenrod color. .. rst-class:: classref-constant -**PALE_GREEN** = ``Color(0.596078, 0.984314, 0.596078, 1)`` +**PALE_GREEN** = ``Color(0.59607846, 0.9843137, 0.59607846, 1)`` :ref:`🔗` Pale green color. @@ -1037,7 +1047,7 @@ Pale green color. .. rst-class:: classref-constant -**PALE_TURQUOISE** = ``Color(0.686275, 0.933333, 0.933333, 1)`` +**PALE_TURQUOISE** = ``Color(0.6862745, 0.93333334, 0.93333334, 1)`` :ref:`🔗` Pale turquoise color. @@ -1045,7 +1055,7 @@ Pale turquoise color. .. rst-class:: classref-constant -**PALE_VIOLET_RED** = ``Color(0.858824, 0.439216, 0.576471, 1)`` +**PALE_VIOLET_RED** = ``Color(0.85882354, 0.4392157, 0.5764706, 1)`` :ref:`🔗` Pale violet red color. @@ -1053,7 +1063,7 @@ Pale violet red color. .. rst-class:: classref-constant -**PAPAYA_WHIP** = ``Color(1, 0.937255, 0.835294, 1)`` +**PAPAYA_WHIP** = ``Color(1, 0.9372549, 0.8352941, 1)`` :ref:`🔗` Papaya whip color. @@ -1061,7 +1071,7 @@ Papaya whip color. .. rst-class:: classref-constant -**PEACH_PUFF** = ``Color(1, 0.854902, 0.72549, 1)`` +**PEACH_PUFF** = ``Color(1, 0.85490197, 0.7254902, 1)`` :ref:`🔗` Peach puff color. @@ -1069,7 +1079,7 @@ Peach puff color. .. rst-class:: classref-constant -**PERU** = ``Color(0.803922, 0.521569, 0.247059, 1)`` +**PERU** = ``Color(0.8039216, 0.52156866, 0.24705882, 1)`` :ref:`🔗` Peru color. @@ -1077,7 +1087,7 @@ Peru color. .. rst-class:: classref-constant -**PINK** = ``Color(1, 0.752941, 0.796078, 1)`` +**PINK** = ``Color(1, 0.7529412, 0.79607844, 1)`` :ref:`🔗` Pink color. @@ -1085,7 +1095,7 @@ Pink color. .. rst-class:: classref-constant -**PLUM** = ``Color(0.866667, 0.627451, 0.866667, 1)`` +**PLUM** = ``Color(0.8666667, 0.627451, 0.8666667, 1)`` :ref:`🔗` Plum color. @@ -1093,7 +1103,7 @@ Plum color. .. rst-class:: classref-constant -**POWDER_BLUE** = ``Color(0.690196, 0.878431, 0.901961, 1)`` +**POWDER_BLUE** = ``Color(0.6901961, 0.8784314, 0.9019608, 1)`` :ref:`🔗` Powder blue color. @@ -1101,7 +1111,7 @@ Powder blue color. .. rst-class:: classref-constant -**PURPLE** = ``Color(0.627451, 0.12549, 0.941176, 1)`` +**PURPLE** = ``Color(0.627451, 0.1254902, 0.9411765, 1)`` :ref:`🔗` Purple color. @@ -1109,7 +1119,7 @@ Purple color. .. rst-class:: classref-constant -**REBECCA_PURPLE** = ``Color(0.4, 0.2, 0.6, 1)`` +**REBECCA_PURPLE** = ``Color(0.4, 0.2, 0.6, 1)`` :ref:`🔗` Rebecca purple color. @@ -1117,7 +1127,7 @@ Rebecca purple color. .. rst-class:: classref-constant -**RED** = ``Color(1, 0, 0, 1)`` +**RED** = ``Color(1, 0, 0, 1)`` :ref:`🔗` Red color. @@ -1125,7 +1135,7 @@ Red color. .. rst-class:: classref-constant -**ROSY_BROWN** = ``Color(0.737255, 0.560784, 0.560784, 1)`` +**ROSY_BROWN** = ``Color(0.7372549, 0.56078434, 0.56078434, 1)`` :ref:`🔗` Rosy brown color. @@ -1133,7 +1143,7 @@ Rosy brown color. .. rst-class:: classref-constant -**ROYAL_BLUE** = ``Color(0.254902, 0.411765, 0.882353, 1)`` +**ROYAL_BLUE** = ``Color(0.25490198, 0.4117647, 0.88235295, 1)`` :ref:`🔗` Royal blue color. @@ -1141,7 +1151,7 @@ Royal blue color. .. rst-class:: classref-constant -**SADDLE_BROWN** = ``Color(0.545098, 0.270588, 0.0745098, 1)`` +**SADDLE_BROWN** = ``Color(0.54509807, 0.27058825, 0.07450981, 1)`` :ref:`🔗` Saddle brown color. @@ -1149,7 +1159,7 @@ Saddle brown color. .. rst-class:: classref-constant -**SALMON** = ``Color(0.980392, 0.501961, 0.447059, 1)`` +**SALMON** = ``Color(0.98039216, 0.5019608, 0.44705883, 1)`` :ref:`🔗` Salmon color. @@ -1157,7 +1167,7 @@ Salmon color. .. rst-class:: classref-constant -**SANDY_BROWN** = ``Color(0.956863, 0.643137, 0.376471, 1)`` +**SANDY_BROWN** = ``Color(0.95686275, 0.6431373, 0.3764706, 1)`` :ref:`🔗` Sandy brown color. @@ -1165,7 +1175,7 @@ Sandy brown color. .. rst-class:: classref-constant -**SEA_GREEN** = ``Color(0.180392, 0.545098, 0.341176, 1)`` +**SEA_GREEN** = ``Color(0.18039216, 0.54509807, 0.34117648, 1)`` :ref:`🔗` Sea green color. @@ -1173,7 +1183,7 @@ Sea green color. .. rst-class:: classref-constant -**SEASHELL** = ``Color(1, 0.960784, 0.933333, 1)`` +**SEASHELL** = ``Color(1, 0.9607843, 0.93333334, 1)`` :ref:`🔗` Seashell color. @@ -1181,7 +1191,7 @@ Seashell color. .. rst-class:: classref-constant -**SIENNA** = ``Color(0.627451, 0.321569, 0.176471, 1)`` +**SIENNA** = ``Color(0.627451, 0.32156864, 0.1764706, 1)`` :ref:`🔗` Sienna color. @@ -1189,7 +1199,7 @@ Sienna color. .. rst-class:: classref-constant -**SILVER** = ``Color(0.752941, 0.752941, 0.752941, 1)`` +**SILVER** = ``Color(0.7529412, 0.7529412, 0.7529412, 1)`` :ref:`🔗` Silver color. @@ -1197,7 +1207,7 @@ Silver color. .. rst-class:: classref-constant -**SKY_BLUE** = ``Color(0.529412, 0.807843, 0.921569, 1)`` +**SKY_BLUE** = ``Color(0.5294118, 0.80784315, 0.92156863, 1)`` :ref:`🔗` Sky blue color. @@ -1205,7 +1215,7 @@ Sky blue color. .. rst-class:: classref-constant -**SLATE_BLUE** = ``Color(0.415686, 0.352941, 0.803922, 1)`` +**SLATE_BLUE** = ``Color(0.41568628, 0.3529412, 0.8039216, 1)`` :ref:`🔗` Slate blue color. @@ -1213,7 +1223,7 @@ Slate blue color. .. rst-class:: classref-constant -**SLATE_GRAY** = ``Color(0.439216, 0.501961, 0.564706, 1)`` +**SLATE_GRAY** = ``Color(0.4392157, 0.5019608, 0.5647059, 1)`` :ref:`🔗` Slate gray color. @@ -1221,7 +1231,7 @@ Slate gray color. .. rst-class:: classref-constant -**SNOW** = ``Color(1, 0.980392, 0.980392, 1)`` +**SNOW** = ``Color(1, 0.98039216, 0.98039216, 1)`` :ref:`🔗` Snow color. @@ -1229,7 +1239,7 @@ Snow color. .. rst-class:: classref-constant -**SPRING_GREEN** = ``Color(0, 1, 0.498039, 1)`` +**SPRING_GREEN** = ``Color(0, 1, 0.49803922, 1)`` :ref:`🔗` Spring green color. @@ -1237,7 +1247,7 @@ Spring green color. .. rst-class:: classref-constant -**STEEL_BLUE** = ``Color(0.27451, 0.509804, 0.705882, 1)`` +**STEEL_BLUE** = ``Color(0.27450982, 0.50980395, 0.7058824, 1)`` :ref:`🔗` Steel blue color. @@ -1245,7 +1255,7 @@ Steel blue color. .. rst-class:: classref-constant -**TAN** = ``Color(0.823529, 0.705882, 0.54902, 1)`` +**TAN** = ``Color(0.8235294, 0.7058824, 0.54901963, 1)`` :ref:`🔗` Tan color. @@ -1253,7 +1263,7 @@ Tan color. .. rst-class:: classref-constant -**TEAL** = ``Color(0, 0.501961, 0.501961, 1)`` +**TEAL** = ``Color(0, 0.5019608, 0.5019608, 1)`` :ref:`🔗` Teal color. @@ -1261,7 +1271,7 @@ Teal color. .. rst-class:: classref-constant -**THISTLE** = ``Color(0.847059, 0.74902, 0.847059, 1)`` +**THISTLE** = ``Color(0.84705883, 0.7490196, 0.84705883, 1)`` :ref:`🔗` Thistle color. @@ -1269,7 +1279,7 @@ Thistle color. .. rst-class:: classref-constant -**TOMATO** = ``Color(1, 0.388235, 0.278431, 1)`` +**TOMATO** = ``Color(1, 0.3882353, 0.2784314, 1)`` :ref:`🔗` Tomato color. @@ -1277,7 +1287,7 @@ Tomato color. .. rst-class:: classref-constant -**TRANSPARENT** = ``Color(1, 1, 1, 0)`` +**TRANSPARENT** = ``Color(1, 1, 1, 0)`` :ref:`🔗` Transparent color (white with zero alpha). @@ -1285,7 +1295,7 @@ Transparent color (white with zero alpha). .. rst-class:: classref-constant -**TURQUOISE** = ``Color(0.25098, 0.878431, 0.815686, 1)`` +**TURQUOISE** = ``Color(0.2509804, 0.8784314, 0.8156863, 1)`` :ref:`🔗` Turquoise color. @@ -1293,7 +1303,7 @@ Turquoise color. .. rst-class:: classref-constant -**VIOLET** = ``Color(0.933333, 0.509804, 0.933333, 1)`` +**VIOLET** = ``Color(0.93333334, 0.50980395, 0.93333334, 1)`` :ref:`🔗` Violet color. @@ -1301,7 +1311,7 @@ Violet color. .. rst-class:: classref-constant -**WEB_GRAY** = ``Color(0.501961, 0.501961, 0.501961, 1)`` +**WEB_GRAY** = ``Color(0.5019608, 0.5019608, 0.5019608, 1)`` :ref:`🔗` Web gray color. @@ -1309,7 +1319,7 @@ Web gray color. .. rst-class:: classref-constant -**WEB_GREEN** = ``Color(0, 0.501961, 0, 1)`` +**WEB_GREEN** = ``Color(0, 0.5019608, 0, 1)`` :ref:`🔗` Web green color. @@ -1317,7 +1327,7 @@ Web green color. .. rst-class:: classref-constant -**WEB_MAROON** = ``Color(0.501961, 0, 0, 1)`` +**WEB_MAROON** = ``Color(0.5019608, 0, 0, 1)`` :ref:`🔗` Web maroon color. @@ -1325,7 +1335,7 @@ Web maroon color. .. rst-class:: classref-constant -**WEB_PURPLE** = ``Color(0.501961, 0, 0.501961, 1)`` +**WEB_PURPLE** = ``Color(0.5019608, 0, 0.5019608, 1)`` :ref:`🔗` Web purple color. @@ -1333,7 +1343,7 @@ Web purple color. .. rst-class:: classref-constant -**WHEAT** = ``Color(0.960784, 0.870588, 0.701961, 1)`` +**WHEAT** = ``Color(0.9607843, 0.87058824, 0.7019608, 1)`` :ref:`🔗` Wheat color. @@ -1341,7 +1351,7 @@ Wheat color. .. rst-class:: classref-constant -**WHITE** = ``Color(1, 1, 1, 1)`` +**WHITE** = ``Color(1, 1, 1, 1)`` :ref:`🔗` White color. @@ -1349,7 +1359,7 @@ White color. .. rst-class:: classref-constant -**WHITE_SMOKE** = ``Color(0.960784, 0.960784, 0.960784, 1)`` +**WHITE_SMOKE** = ``Color(0.9607843, 0.9607843, 0.9607843, 1)`` :ref:`🔗` White smoke color. @@ -1357,7 +1367,7 @@ White smoke color. .. rst-class:: classref-constant -**YELLOW** = ``Color(1, 1, 0, 1)`` +**YELLOW** = ``Color(1, 1, 0, 1)`` :ref:`🔗` Yellow color. @@ -1365,7 +1375,7 @@ Yellow color. .. rst-class:: classref-constant -**YELLOW_GREEN** = ``Color(0.603922, 0.803922, 0.196078, 1)`` +**YELLOW_GREEN** = ``Color(0.6039216, 0.8039216, 0.19607843, 1)`` :ref:`🔗` Yellow green color. @@ -1382,10 +1392,12 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **a** = ``1.0`` +:ref:`float` **a** = ``1.0`` :ref:`🔗` The color's alpha component, typically on the range of 0 to 1. A value of 0 means that the color is fully transparent. A value of 1 means that the color is fully opaque. +\ **Note:** The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. The :ref:`linear_to_srgb()` and :ref:`srgb_to_linear()` methods do not affect the alpha channel. + .. rst-class:: classref-item-separator ---- @@ -1394,7 +1406,7 @@ The color's alpha component, typically on the range of 0 to 1. A value of 0 mean .. rst-class:: classref-property -:ref:`int` **a8** = ``255`` +:ref:`int` **a8** = ``255`` :ref:`🔗` Wrapper for :ref:`a` that uses the range 0 to 255, instead of 0 to 1. @@ -1406,7 +1418,7 @@ Wrapper for :ref:`a` that uses the range 0 to 255, inste .. rst-class:: classref-property -:ref:`float` **b** = ``0.0`` +:ref:`float` **b** = ``0.0`` :ref:`🔗` The color's blue component, typically on the range of 0 to 1. @@ -1418,7 +1430,7 @@ The color's blue component, typically on the range of 0 to 1. .. rst-class:: classref-property -:ref:`int` **b8** = ``0`` +:ref:`int` **b8** = ``0`` :ref:`🔗` Wrapper for :ref:`b` that uses the range 0 to 255, instead of 0 to 1. @@ -1430,7 +1442,7 @@ Wrapper for :ref:`b` that uses the range 0 to 255, inste .. rst-class:: classref-property -:ref:`float` **g** = ``0.0`` +:ref:`float` **g** = ``0.0`` :ref:`🔗` The color's green component, typically on the range of 0 to 1. @@ -1442,7 +1454,7 @@ The color's green component, typically on the range of 0 to 1. .. rst-class:: classref-property -:ref:`int` **g8** = ``0`` +:ref:`int` **g8** = ``0`` :ref:`🔗` Wrapper for :ref:`g` that uses the range 0 to 255, instead of 0 to 1. @@ -1454,7 +1466,7 @@ Wrapper for :ref:`g` that uses the range 0 to 255, inste .. rst-class:: classref-property -:ref:`float` **h** = ``0.0`` +:ref:`float` **h** = ``0.0`` :ref:`🔗` The HSV hue of this color, on the range 0 to 1. @@ -1462,11 +1474,47 @@ The HSV hue of this color, on the range 0 to 1. ---- +.. _class_Color_property_ok_hsl_h: + +.. rst-class:: classref-property + +:ref:`float` **ok_hsl_h** = ``0.0`` :ref:`🔗` + +The OKHSL hue of this color, on the range 0 to 1. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Color_property_ok_hsl_l: + +.. rst-class:: classref-property + +:ref:`float` **ok_hsl_l** = ``0.0`` :ref:`🔗` + +The OKHSL lightness of this color, on the range 0 to 1. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Color_property_ok_hsl_s: + +.. rst-class:: classref-property + +:ref:`float` **ok_hsl_s** = ``0.0`` :ref:`🔗` + +The OKHSL saturation of this color, on the range 0 to 1. + +.. rst-class:: classref-item-separator + +---- + .. _class_Color_property_r: .. rst-class:: classref-property -:ref:`float` **r** = ``0.0`` +:ref:`float` **r** = ``0.0`` :ref:`🔗` The color's red component, typically on the range of 0 to 1. @@ -1478,7 +1526,7 @@ The color's red component, typically on the range of 0 to 1. .. rst-class:: classref-property -:ref:`int` **r8** = ``0`` +:ref:`int` **r8** = ``0`` :ref:`🔗` Wrapper for :ref:`r` that uses the range 0 to 255, instead of 0 to 1. @@ -1490,7 +1538,7 @@ Wrapper for :ref:`r` that uses the range 0 to 255, inste .. rst-class:: classref-property -:ref:`float` **s** = ``0.0`` +:ref:`float` **s** = ``0.0`` :ref:`🔗` The HSV saturation of this color, on the range 0 to 1. @@ -1502,7 +1550,7 @@ The HSV saturation of this color, on the range 0 to 1. .. rst-class:: classref-property -:ref:`float` **v** = ``0.0`` +:ref:`float` **v** = ``0.0`` :ref:`🔗` The HSV value (brightness) of this color, on the range 0 to 1. @@ -1519,11 +1567,11 @@ Constructor Descriptions .. rst-class:: classref-constructor -:ref:`Color` **Color**\ (\ ) +:ref:`Color` **Color**\ (\ ) :ref:`🔗` Constructs a default **Color** from opaque black. This is the same as :ref:`BLACK`. -\ **Note:** in C#, constructs an empty color with all of its components set to ``0.0`` (transparent black). +\ **Note:** In C#, this constructs a **Color** with all of its components set to ``0.0`` (transparent black). .. rst-class:: classref-item-separator @@ -1637,7 +1685,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Color` **blend**\ (\ over\: :ref:`Color`\ ) |const| +:ref:`Color` **blend**\ (\ over\: :ref:`Color`\ ) |const| :ref:`🔗` Returns a new color resulting from overlaying this color over the given color. In a painting program, you can imagine it as the ``over`` color painted over this color (including alpha). @@ -1666,9 +1714,9 @@ Returns a new color resulting from overlaying this color over the given color. I .. rst-class:: classref-method -:ref:`Color` **clamp**\ (\ min\: :ref:`Color` = Color(0, 0, 0, 0), max\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| +:ref:`Color` **clamp**\ (\ min\: :ref:`Color` = Color(0, 0, 0, 0), max\: :ref:`Color` = Color(1, 1, 1, 1)\ ) |const| :ref:`🔗` -Returns a new color with all components clamped between the components of ``min`` and ``max``, by running :ref:`@GlobalScope.clamp` on each component. +Returns a new color with all components clamped between the components of ``min`` and ``max``, by running :ref:`@GlobalScope.clamp()` on each component. .. rst-class:: classref-item-separator @@ -1678,9 +1726,9 @@ Returns a new color with all components clamped between the components of ``min` .. rst-class:: classref-method -:ref:`Color` **darkened**\ (\ amount\: :ref:`float`\ ) |const| +:ref:`Color` **darkened**\ (\ amount\: :ref:`float`\ ) |const| :ref:`🔗` -Returns a new color resulting from making this color darker by the specified ``amount`` (ratio from 0.0 to 1.0). See also :ref:`lightened`. +Returns a new color resulting from making this color darker by the specified ``amount`` (ratio from 0.0 to 1.0). See also :ref:`lightened()`. .. tabs:: @@ -1705,7 +1753,7 @@ Returns a new color resulting from making this color darker by the specified ``a .. rst-class:: classref-method -:ref:`Color` **from_hsv**\ (\ h\: :ref:`float`, s\: :ref:`float`, v\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| +:ref:`Color` **from_hsv**\ (\ h\: :ref:`float`, s\: :ref:`float`, v\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| :ref:`🔗` Constructs a color from an `HSV profile `__. The hue (``h``), saturation (``s``), and value (``v``) are typically between 0.0 and 1.0. @@ -1730,7 +1778,7 @@ Constructs a color from an `HSV profile ` **from_ok_hsl**\ (\ h\: :ref:`float`, s\: :ref:`float`, l\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| +:ref:`Color` **from_ok_hsl**\ (\ h\: :ref:`float`, s\: :ref:`float`, l\: :ref:`float`, alpha\: :ref:`float` = 1.0\ ) |static| :ref:`🔗` Constructs a color from an `OK HSL profile `__. The hue (``h``), saturation (``s``), and lightness (``l``) are typically between 0.0 and 1.0. @@ -1747,6 +1795,26 @@ Constructs a color from an `OK HSL profile ` **from_rgba8**\ (\ r8\: :ref:`int`, g8\: :ref:`int`, b8\: :ref:`int`, a8\: :ref:`int` = 255\ ) |static| :ref:`🔗` + +Returns a **Color** constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. + +:: + + var red = Color.from_rgba8(255, 0, 0) # Same as Color(1, 0, 0). + var dark_blue = Color.from_rgba8(0, 0, 51) # Same as Color(0, 0, 0.2). + var my_color = Color.from_rgba8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). + +\ **Note:** Due to the lower precision of :ref:`from_rgba8()` compared to the standard **Color** constructor, a color created with :ref:`from_rgba8()` will generally not be equal to the same color created with the standard **Color** constructor. Use :ref:`is_equal_approx()` for comparisons to avoid issues with floating-point precision error. + .. rst-class:: classref-item-separator ---- @@ -1755,9 +1823,9 @@ Constructs a color from an `OK HSL profile ` **from_rgbe9995**\ (\ rgbe\: :ref:`int`\ ) |static| +:ref:`Color` **from_rgbe9995**\ (\ rgbe\: :ref:`int`\ ) |static| :ref:`🔗` -Decodes a **Color** from a RGBE9995 format integer. See :ref:`Image.FORMAT_RGBE9995`. +Decodes a **Color** from an RGBE9995 format integer. See :ref:`Image.FORMAT_RGBE9995`. .. rst-class:: classref-item-separator @@ -1767,10 +1835,12 @@ Decodes a **Color** from a RGBE9995 format integer. See :ref:`Image.FORMAT_RGBE9 .. rst-class:: classref-method -:ref:`Color` **from_string**\ (\ str\: :ref:`String`, default\: :ref:`Color`\ ) |static| +:ref:`Color` **from_string**\ (\ str\: :ref:`String`, default\: :ref:`Color`\ ) |static| :ref:`🔗` Creates a **Color** from the given string, which can be either an HTML color code or a named color (case-insensitive). Returns ``default`` if the color cannot be inferred from the string. +If you want to create a color from String in a constant expression, use the equivalent constructor instead (i.e. ``Color("color string")``). + .. rst-class:: classref-item-separator ---- @@ -1779,11 +1849,11 @@ Creates a **Color** from the given string, which can be either an HTML color cod .. rst-class:: classref-method -:ref:`float` **get_luminance**\ (\ ) |const| +:ref:`float` **get_luminance**\ (\ ) |const| :ref:`🔗` Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclusive). This is useful when determining light or dark color. Colors with a luminance smaller than 0.5 can be generally considered dark. -\ **Note:** :ref:`get_luminance` relies on the color being in the linear color space to return an accurate relative luminance value. If the color is in the sRGB color space, use :ref:`srgb_to_linear` to convert it to the linear color space first. +\ **Note:** :ref:`get_luminance()` relies on the color being in the linear color space to return an accurate relative luminance value. If the color is in the sRGB color space, use :ref:`srgb_to_linear()` to convert it to the linear color space first. .. rst-class:: classref-item-separator @@ -1793,9 +1863,9 @@ Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclus .. rst-class:: classref-method -:ref:`Color` **hex**\ (\ hex\: :ref:`int`\ ) |static| +:ref:`Color` **hex**\ (\ hex\: :ref:`int`\ ) |static| :ref:`🔗` -Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel). +Returns the **Color** associated with the provided ``hex`` integer in 32-bit RGBA format (8 bits per channel). This method is the inverse of :ref:`to_rgba32()`. In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRGGBBAA"``). @@ -1816,6 +1886,8 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima +If you want to use hex notation in a constant expression, use the equivalent constructor instead (i.e. ``Color(0xRRGGBBAA)``). + .. rst-class:: classref-item-separator ---- @@ -1824,9 +1896,9 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima .. rst-class:: classref-method -:ref:`Color` **hex64**\ (\ hex\: :ref:`int`\ ) |static| +:ref:`Color` **hex64**\ (\ hex\: :ref:`int`\ ) |static| :ref:`🔗` -Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel). +Returns the **Color** associated with the provided ``hex`` integer in 64-bit RGBA format (16 bits per channel). This method is the inverse of :ref:`to_rgba64()`. In GDScript and C#, the :ref:`int` is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRRRGGGGBBBBAAAA"``). @@ -1838,7 +1910,7 @@ In GDScript and C#, the :ref:`int` is best visualized with hexadecima .. rst-class:: classref-method -:ref:`Color` **html**\ (\ rgba\: :ref:`String`\ ) |static| +:ref:`Color` **html**\ (\ rgba\: :ref:`String`\ ) |static| :ref:`🔗` Returns a new color from ``rgba``, an HTML hexadecimal color string. ``rgba`` is not case-sensitive, and may be prefixed by a hash sign (``#``). @@ -1869,9 +1941,9 @@ Returns a new color from ``rgba``, an HTML hexadecimal color string. ``rgba`` is .. rst-class:: classref-method -:ref:`bool` **html_is_valid**\ (\ color\: :ref:`String`\ ) |static| +:ref:`bool` **html_is_valid**\ (\ color\: :ref:`String`\ ) |static| :ref:`🔗` -Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The string must be a hexadecimal value (case-insensitive) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign (``#``). This method is identical to :ref:`String.is_valid_html_color`. +Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The string must be a hexadecimal value (case-insensitive) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign (``#``). This method is identical to :ref:`String.is_valid_html_color()`. .. tabs:: @@ -1882,7 +1954,7 @@ Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The stri Color.html_is_valid("#55AAFF20") # Returns true Color.html_is_valid("55AAFF") # Returns true Color.html_is_valid("#F2C") # Returns true - + Color.html_is_valid("#AABBC") # Returns false Color.html_is_valid("#55aaFF5") # Returns false @@ -1892,7 +1964,7 @@ Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The stri Color.HtmlIsValid("#55AAFF20"); // Returns true Color.HtmlIsValid("55AAFF"); // Returns true Color.HtmlIsValid("#F2C"); // Returns true - + Color.HtmlIsValid("#AABBC"); // Returns false Color.HtmlIsValid("#55aaFF5"); // Returns false @@ -1906,7 +1978,7 @@ Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The stri .. rst-class:: classref-method -:ref:`Color` **inverted**\ (\ ) |const| +:ref:`Color` **inverted**\ (\ ) |const| :ref:`🔗` Returns the color with its :ref:`r`, :ref:`g`, and :ref:`b` components inverted (``(1 - r, 1 - g, 1 - b, a)``). @@ -1935,9 +2007,9 @@ Returns the color with its :ref:`r`, :ref:`g` **is_equal_approx**\ (\ to\: :ref:`Color`\ ) |const| +:ref:`bool` **is_equal_approx**\ (\ to\: :ref:`Color`\ ) |const| :ref:`🔗` -Returns ``true`` if this color and ``to`` are approximately equal, by running :ref:`@GlobalScope.is_equal_approx` on each component. +Returns ``true`` if this color and ``to`` are approximately equal, by running :ref:`@GlobalScope.is_equal_approx()` on each component. .. rst-class:: classref-item-separator @@ -1947,9 +2019,9 @@ Returns ``true`` if this color and ``to`` are approximately equal, by running :r .. rst-class:: classref-method -:ref:`Color` **lerp**\ (\ to\: :ref:`Color`, weight\: :ref:`float`\ ) |const| +:ref:`Color` **lerp**\ (\ to\: :ref:`Color`, weight\: :ref:`float`\ ) |const| :ref:`🔗` -Returns the linear interpolation between this color's components and ``to``'s components. The interpolation factor ``weight`` should be between 0.0 and 1.0 (inclusive). See also :ref:`@GlobalScope.lerp`. +Returns the linear interpolation between this color's components and ``to``'s components. The interpolation factor ``weight`` should be between 0.0 and 1.0 (inclusive). See also :ref:`@GlobalScope.lerp()`. .. tabs:: @@ -1958,7 +2030,7 @@ Returns the linear interpolation between this color's components and ``to``'s co var red = Color(1.0, 0.0, 0.0) var aqua = Color(0.0, 1.0, 0.8) - + red.lerp(aqua, 0.2) # Returns Color(0.8, 0.2, 0.16) red.lerp(aqua, 0.5) # Returns Color(0.5, 0.5, 0.4) red.lerp(aqua, 1.0) # Returns Color(0.0, 1.0, 0.8) @@ -1967,7 +2039,7 @@ Returns the linear interpolation between this color's components and ``to``'s co var red = new Color(1.0f, 0.0f, 0.0f); var aqua = new Color(0.0f, 1.0f, 0.8f); - + red.Lerp(aqua, 0.2f); // Returns Color(0.8f, 0.2f, 0.16f) red.Lerp(aqua, 0.5f); // Returns Color(0.5f, 0.5f, 0.4f) red.Lerp(aqua, 1.0f); // Returns Color(0.0f, 1.0f, 0.8f) @@ -1982,9 +2054,9 @@ Returns the linear interpolation between this color's components and ``to``'s co .. rst-class:: classref-method -:ref:`Color` **lightened**\ (\ amount\: :ref:`float`\ ) |const| +:ref:`Color` **lightened**\ (\ amount\: :ref:`float`\ ) |const| :ref:`🔗` -Returns a new color resulting from making this color lighter by the specified ``amount``, which should be a ratio from 0.0 to 1.0. See also :ref:`darkened`. +Returns a new color resulting from making this color lighter by the specified ``amount``, which should be a ratio from 0.0 to 1.0. See also :ref:`darkened()`. .. tabs:: @@ -2009,9 +2081,11 @@ Returns a new color resulting from making this color lighter by the specified `` .. rst-class:: classref-method -:ref:`Color` **linear_to_srgb**\ (\ ) |const| +:ref:`Color` **linear_to_srgb**\ (\ ) |const| :ref:`🔗` + +Returns the color converted to the `sRGB `__ color space. This method assumes the original color is in the linear color space. See also :ref:`srgb_to_linear()` which performs the opposite operation. -Returns the color converted to the `sRGB `__ color space. This method assumes the original color is in the linear color space. See also :ref:`srgb_to_linear` which performs the opposite operation. +\ **Note:** The color's :ref:`a`\ lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. .. rst-class:: classref-item-separator @@ -2021,9 +2095,11 @@ Returns the color converted to the `sRGB `__ .. rst-class:: classref-method -:ref:`Color` **srgb_to_linear**\ (\ ) |const| +:ref:`Color` **srgb_to_linear**\ (\ ) |const| :ref:`🔗` + +Returns the color converted to the linear color space. This method assumes the original color already is in the sRGB color space. See also :ref:`linear_to_srgb()` which performs the opposite operation. -Returns the color converted to the linear color space. This method assumes the original color already is in the sRGB color space. See also :ref:`linear_to_srgb` which performs the opposite operation. +\ **Note:** The color's :ref:`a`\ lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. .. rst-class:: classref-item-separator @@ -2033,7 +2109,7 @@ Returns the color converted to the linear color space. This method assumes the o .. rst-class:: classref-method -:ref:`int` **to_abgr32**\ (\ ) |const| +:ref:`int` **to_abgr32**\ (\ ) |const| :ref:`🔗` Returns the color converted to a 32-bit integer in ABGR format (each component is 8 bits). ABGR is the reversed version of the default RGBA format. @@ -2060,7 +2136,7 @@ Returns the color converted to a 32-bit integer in ABGR format (each component i .. rst-class:: classref-method -:ref:`int` **to_abgr64**\ (\ ) |const| +:ref:`int` **to_abgr64**\ (\ ) |const| :ref:`🔗` Returns the color converted to a 64-bit integer in ABGR format (each component is 16 bits). ABGR is the reversed version of the default RGBA format. @@ -2087,7 +2163,7 @@ Returns the color converted to a 64-bit integer in ABGR format (each component i .. rst-class:: classref-method -:ref:`int` **to_argb32**\ (\ ) |const| +:ref:`int` **to_argb32**\ (\ ) |const| :ref:`🔗` Returns the color converted to a 32-bit integer in ARGB format (each component is 8 bits). ARGB is more compatible with DirectX. @@ -2114,7 +2190,7 @@ Returns the color converted to a 32-bit integer in ARGB format (each component i .. rst-class:: classref-method -:ref:`int` **to_argb64**\ (\ ) |const| +:ref:`int` **to_argb64**\ (\ ) |const| :ref:`🔗` Returns the color converted to a 64-bit integer in ARGB format (each component is 16 bits). ARGB is more compatible with DirectX. @@ -2141,7 +2217,7 @@ Returns the color converted to a 64-bit integer in ARGB format (each component i .. rst-class:: classref-method -:ref:`String` **to_html**\ (\ with_alpha\: :ref:`bool` = true\ ) |const| +:ref:`String` **to_html**\ (\ with_alpha\: :ref:`bool` = true\ ) |const| :ref:`🔗` Returns the color converted to an HTML hexadecimal color :ref:`String` in RGBA format, without the hash (``#``) prefix. @@ -2172,9 +2248,9 @@ Setting ``with_alpha`` to ``false``, excludes alpha from the hexadecimal string, .. rst-class:: classref-method -:ref:`int` **to_rgba32**\ (\ ) |const| +:ref:`int` **to_rgba32**\ (\ ) |const| :ref:`🔗` -Returns the color converted to a 32-bit integer in RGBA format (each component is 8 bits). RGBA is Godot's default format. +Returns the color converted to a 32-bit integer in RGBA format (each component is 8 bits). RGBA is Godot's default format. This method is the inverse of :ref:`hex()`. .. tabs:: @@ -2199,9 +2275,9 @@ Returns the color converted to a 32-bit integer in RGBA format (each component i .. rst-class:: classref-method -:ref:`int` **to_rgba64**\ (\ ) |const| +:ref:`int` **to_rgba64**\ (\ ) |const| :ref:`🔗` -Returns the color converted to a 64-bit integer in RGBA format (each component is 16 bits). RGBA is Godot's default format. +Returns the color converted to a 64-bit integer in RGBA format (each component is 16 bits). RGBA is Godot's default format. This method is the inverse of :ref:`hex64()`. .. tabs:: @@ -2231,11 +2307,11 @@ Operator Descriptions .. rst-class:: classref-operator -:ref:`bool` **operator !=**\ (\ right\: :ref:`Color`\ ) +:ref:`bool` **operator !=**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` Returns ``true`` if the colors are not exactly equal. -\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. .. rst-class:: classref-item-separator @@ -2245,7 +2321,7 @@ Returns ``true`` if the colors are not exactly equal. .. rst-class:: classref-operator -:ref:`Color` **operator ***\ (\ right\: :ref:`Color`\ ) +:ref:`Color` **operator ***\ (\ right\: :ref:`Color`\ ) :ref:`🔗` Multiplies each component of the **Color** by the components of the given **Color**. @@ -2257,7 +2333,7 @@ Multiplies each component of the **Color** by the components of the given **Colo .. rst-class:: classref-operator -:ref:`Color` **operator ***\ (\ right\: :ref:`float`\ ) +:ref:`Color` **operator ***\ (\ right\: :ref:`float`\ ) :ref:`🔗` Multiplies each component of the **Color** by the given :ref:`float`. @@ -2269,7 +2345,7 @@ Multiplies each component of the **Color** by the given :ref:`float .. rst-class:: classref-operator -:ref:`Color` **operator ***\ (\ right\: :ref:`int`\ ) +:ref:`Color` **operator ***\ (\ right\: :ref:`int`\ ) :ref:`🔗` Multiplies each component of the **Color** by the given :ref:`int`. @@ -2281,7 +2357,7 @@ Multiplies each component of the **Color** by the given :ref:`int`. .. rst-class:: classref-operator -:ref:`Color` **operator +**\ (\ right\: :ref:`Color`\ ) +:ref:`Color` **operator +**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` Adds each component of the **Color** with the components of the given **Color**. @@ -2293,7 +2369,7 @@ Adds each component of the **Color** with the components of the given **Color**. .. rst-class:: classref-operator -:ref:`Color` **operator -**\ (\ right\: :ref:`Color`\ ) +:ref:`Color` **operator -**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` Subtracts each component of the **Color** by the components of the given **Color**. @@ -2305,7 +2381,7 @@ Subtracts each component of the **Color** by the components of the given **Color .. rst-class:: classref-operator -:ref:`Color` **operator /**\ (\ right\: :ref:`Color`\ ) +:ref:`Color` **operator /**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` Divides each component of the **Color** by the components of the given **Color**. @@ -2317,7 +2393,7 @@ Divides each component of the **Color** by the components of the given **Color** .. rst-class:: classref-operator -:ref:`Color` **operator /**\ (\ right\: :ref:`float`\ ) +:ref:`Color` **operator /**\ (\ right\: :ref:`float`\ ) :ref:`🔗` Divides each component of the **Color** by the given :ref:`float`. @@ -2329,7 +2405,7 @@ Divides each component of the **Color** by the given :ref:`float`. .. rst-class:: classref-operator -:ref:`Color` **operator /**\ (\ right\: :ref:`int`\ ) +:ref:`Color` **operator /**\ (\ right\: :ref:`int`\ ) :ref:`🔗` Divides each component of the **Color** by the given :ref:`int`. @@ -2341,11 +2417,11 @@ Divides each component of the **Color** by the given :ref:`int`. .. rst-class:: classref-operator -:ref:`bool` **operator ==**\ (\ right\: :ref:`Color`\ ) +:ref:`bool` **operator ==**\ (\ right\: :ref:`Color`\ ) :ref:`🔗` Returns ``true`` if the colors are exactly equal. -\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx` instead, which is more reliable. +\ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx()` instead, which is more reliable. .. rst-class:: classref-item-separator @@ -2355,7 +2431,7 @@ Returns ``true`` if the colors are exactly equal. .. rst-class:: classref-operator -:ref:`float` **operator []**\ (\ index\: :ref:`int`\ ) +:ref:`float` **operator []**\ (\ index\: :ref:`int`\ ) :ref:`🔗` Access color components using their index. ``[0]`` is equivalent to :ref:`r`, ``[1]`` is equivalent to :ref:`g`, ``[2]`` is equivalent to :ref:`b`, and ``[3]`` is equivalent to :ref:`a`. @@ -2367,7 +2443,7 @@ Access color components using their index. ``[0]`` is equivalent to :ref:`r` **operator unary+**\ (\ ) +:ref:`Color` **operator unary+**\ (\ ) :ref:`🔗` Returns the same value as if the ``+`` was not there. Unary ``+`` does nothing, but sometimes it can make your code more readable. @@ -2379,11 +2455,12 @@ Returns the same value as if the ``+`` was not there. Unary ``+`` does nothing, .. rst-class:: classref-operator -:ref:`Color` **operator unary-**\ (\ ) +:ref:`Color` **operator unary-**\ (\ ) :ref:`🔗` -Inverts the given color. This is equivalent to ``Color.WHITE - c`` or ``Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a)``. Unlike with :ref:`inverted`, the :ref:`a` component is inverted, too. +Inverts the given color. This is equivalent to ``Color.WHITE - c`` or ``Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a)``. Unlike with :ref:`inverted()`, the :ref:`a` component is inverted, too. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_colorpalette.rst b/classes/class_colorpalette.rst new file mode 100644 index 00000000000..fcffacd9bc5 --- /dev/null +++ b/classes/class_colorpalette.rst @@ -0,0 +1,68 @@ +: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/ColorPalette.xml. + +.. _class_ColorPalette: + +ColorPalette +============ + +**Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` + +A resource class for managing a palette of colors, which can be loaded and saved using :ref:`ColorPicker`. + +.. rst-class:: classref-introduction-group + +Description +----------- + +The **ColorPalette** resource is designed to store and manage a collection of colors. This resource is useful in scenarios where a predefined set of colors is required, such as for creating themes, designing user interfaces, or managing game assets. The built-in :ref:`ColorPicker` control can also make use of **ColorPalette** without additional code. + +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------------------------------+---------------------------------------------------+------------------------+ + | :ref:`PackedColorArray` | :ref:`colors` | ``PackedColorArray()`` | + +-------------------------------------------------+---------------------------------------------------+------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_ColorPalette_property_colors: + +.. rst-class:: classref-property + +:ref:`PackedColorArray` **colors** = ``PackedColorArray()`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_colors**\ (\ value\: :ref:`PackedColorArray`\ ) +- :ref:`PackedColorArray` **get_colors**\ (\ ) + +A :ref:`PackedColorArray` containing the colors in the palette. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedColorArray` for more details. + +.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` +.. |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.)` +.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` +.. |void| replace:: :abbr:`void (No return value.)` diff --git a/classes/class_colorpicker.rst b/classes/class_colorpicker.rst index d7212ec9eaf..d85c662708c 100644 --- a/classes/class_colorpicker.rst +++ b/classes/class_colorpicker.rst @@ -28,7 +28,7 @@ A widget that provides an interface for selecting or modifying a color. It can o Tutorials --------- -- `Tween Demo `__ +- `Tween Interpolation Demo `__ .. rst-class:: classref-reftable-group @@ -51,6 +51,8 @@ Properties +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`edit_alpha` | ``true`` | +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`edit_intensity` | ``true`` | + +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ | :ref:`bool` | :ref:`hex_visible` | ``true`` | +----------------------------------------------------------+----------------------------------------------------------------------------+-----------------------+ | :ref:`PickerShapeType` | :ref:`picker_shape` | ``0`` | @@ -92,47 +94,59 @@ Theme Properties .. table:: :widths: auto - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`int` | :ref:`center_slider_grabbers` | ``1`` | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`int` | :ref:`h_width` | ``30`` | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`int` | :ref:`label_width` | ``10`` | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`int` | :ref:`margin` | ``4`` | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`int` | :ref:`sv_height` | ``256`` | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`int` | :ref:`sv_width` | ``256`` | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`add_preset` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`bar_arrow` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`color_hue` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`color_okhsl_hue` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`expanded_arrow` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`folded_arrow` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`overbright_indicator` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`picker_cursor` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`sample_bg` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`sample_revert` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`screen_picker` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`shape_circle` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`shape_rect` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ - | :ref:`Texture2D` | :ref:`shape_rect_wheel` | | - +-----------------------------------+----------------------------------------------------------------------------------------+---------+ + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Color` | :ref:`focused_not_editing_cursor_color` | ``Color(1, 1, 1, 0.275)`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`center_slider_grabbers` | ``1`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`h_width` | ``30`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`label_width` | ``10`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`margin` | ``4`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`sv_height` | ``256`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`int` | :ref:`sv_width` | ``256`` | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`add_preset` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`bar_arrow` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`color_hue` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`color_script` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`expanded_arrow` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`folded_arrow` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`menu_option` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`overbright_indicator` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`picker_cursor` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`picker_cursor_bg` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`sample_bg` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`sample_revert` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`screen_picker` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`shape_circle` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`shape_rect` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`Texture2D` | :ref:`shape_rect_wheel` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`StyleBox` | :ref:`picker_focus_circle` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`StyleBox` | :ref:`picker_focus_rectangle` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ + | :ref:`StyleBox` | :ref:`sample_focus` | | + +-----------------------------------+---------------------------------------------------------------------------------------------------------+---------------------------+ .. rst-class:: classref-section-separator @@ -147,7 +161,7 @@ Signals .. rst-class:: classref-signal -**color_changed**\ (\ color\: :ref:`Color`\ ) +**color_changed**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when the color is changed. @@ -159,7 +173,7 @@ Emitted when the color is changed. .. rst-class:: classref-signal -**preset_added**\ (\ color\: :ref:`Color`\ ) +**preset_added**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when a preset is added. @@ -171,7 +185,7 @@ Emitted when a preset is added. .. rst-class:: classref-signal -**preset_removed**\ (\ color\: :ref:`Color`\ ) +**preset_removed**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when a preset is removed. @@ -188,7 +202,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **ColorModeType**: +enum **ColorModeType**: :ref:`🔗` .. _class_ColorPicker_constant_MODE_RGB: @@ -196,7 +210,7 @@ enum **ColorModeType**: :ref:`ColorModeType` **MODE_RGB** = ``0`` -Allows editing the color with Red/Green/Blue sliders. +Allows editing the color with Red/Green/Blue sliders in sRGB color space. .. _class_ColorPicker_constant_MODE_HSV: @@ -212,7 +226,17 @@ Allows editing the color with Hue/Saturation/Value sliders. :ref:`ColorModeType` **MODE_RAW** = ``2`` -Allows the color R, G, B component values to go beyond 1.0, which can be used for certain special operations that require it (like tinting without darkening or rendering sprites in HDR). +**Deprecated:** This is replaced by :ref:`MODE_LINEAR`. + + + +.. _class_ColorPicker_constant_MODE_LINEAR: + +.. rst-class:: classref-enumeration-constant + +:ref:`ColorModeType` **MODE_LINEAR** = ``2`` + +Allows editing the color with Red/Green/Blue sliders in linear color space. .. _class_ColorPicker_constant_MODE_OKHSL: @@ -234,7 +258,7 @@ OKHSL is a new color space similar to HSL but that better match perception by le .. rst-class:: classref-enumeration -enum **PickerShapeType**: +enum **PickerShapeType**: :ref:`🔗` .. _class_ColorPicker_constant_SHAPE_HSV_RECTANGLE: @@ -276,6 +300,22 @@ HSL OK Color Model circle color space. The color space shape and the shape select button are hidden. Can't be selected from the shapes popup. +.. _class_ColorPicker_constant_SHAPE_OK_HS_RECTANGLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_OK_HS_RECTANGLE** = ``5`` + +OKHSL Color Model rectangle with constant lightness. + +.. _class_ColorPicker_constant_SHAPE_OK_HL_RECTANGLE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PickerShapeType` **SHAPE_OK_HL_RECTANGLE** = ``6`` + +OKHSL Color Model rectangle with constant saturation. + .. rst-class:: classref-section-separator ---- @@ -289,7 +329,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **can_add_swatches** = ``true`` +:ref:`bool` **can_add_swatches** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -306,7 +346,7 @@ If ``true``, it's possible to add presets under Swatches. If ``false``, the butt .. rst-class:: classref-property -:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -323,14 +363,14 @@ The currently selected color. .. rst-class:: classref-property -:ref:`ColorModeType` **color_mode** = ``0`` +:ref:`ColorModeType` **color_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_color_mode**\ (\ value\: :ref:`ColorModeType`\ ) - :ref:`ColorModeType` **get_color_mode**\ (\ ) -The currently selected color mode. See :ref:`ColorModeType`. +The currently selected color mode. .. rst-class:: classref-item-separator @@ -340,7 +380,7 @@ The currently selected color mode. See :ref:`ColorModeType` **color_modes_visible** = ``true`` +:ref:`bool` **color_modes_visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -357,7 +397,7 @@ If ``true``, the color mode buttons are visible. .. rst-class:: classref-property -:ref:`bool` **deferred_mode** = ``false`` +:ref:`bool` **deferred_mode** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -374,7 +414,7 @@ If ``true``, the color will apply only after the user releases the mouse button, .. rst-class:: classref-property -:ref:`bool` **edit_alpha** = ``true`` +:ref:`bool` **edit_alpha** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -387,11 +427,28 @@ If ``true``, shows an alpha channel slider (opacity). ---- +.. _class_ColorPicker_property_edit_intensity: + +.. rst-class:: classref-property + +:ref:`bool` **edit_intensity** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_edit_intensity**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_editing_intensity**\ (\ ) + +If ``true``, shows an intensity slider. The intensity is applied as follows: multiply the color by ``2 ** intensity`` in linear RGB space, and then convert it back to sRGB. + +.. rst-class:: classref-item-separator + +---- + .. _class_ColorPicker_property_hex_visible: .. rst-class:: classref-property -:ref:`bool` **hex_visible** = ``true`` +:ref:`bool` **hex_visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -408,14 +465,14 @@ If ``true``, the hex color code input field is visible. .. rst-class:: classref-property -:ref:`PickerShapeType` **picker_shape** = ``0`` +:ref:`PickerShapeType` **picker_shape** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_picker_shape**\ (\ value\: :ref:`PickerShapeType`\ ) - :ref:`PickerShapeType` **get_picker_shape**\ (\ ) -The shape of the color space view. See :ref:`PickerShapeType`. +The shape of the color space view. .. rst-class:: classref-item-separator @@ -425,7 +482,7 @@ The shape of the color space view. See :ref:`PickerShapeType` **presets_visible** = ``true`` +:ref:`bool` **presets_visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -442,7 +499,7 @@ If ``true``, the Swatches and Recent Colors presets are visible. .. rst-class:: classref-property -:ref:`bool` **sampler_visible** = ``true`` +:ref:`bool` **sampler_visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -459,7 +516,7 @@ If ``true``, the color sampler and color preview are visible. .. rst-class:: classref-property -:ref:`bool` **sliders_visible** = ``true`` +:ref:`bool` **sliders_visible** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -481,7 +538,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **add_preset**\ (\ color\: :ref:`Color`\ ) +|void| **add_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Adds the given color to a list of color presets. The presets are displayed in the color picker and the user will be able to select them. @@ -495,7 +552,7 @@ Adds the given color to a list of color presets. The presets are displayed in th .. rst-class:: classref-method -|void| **add_recent_preset**\ (\ color\: :ref:`Color`\ ) +|void| **add_recent_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Adds the given color to a list of color recent presets so that it can be picked later. Recent presets are the colors that were picked recently, a new preset is automatically created and added to recent presets when you pick a new color. @@ -509,7 +566,7 @@ Adds the given color to a list of color recent presets so that it can be picked .. rst-class:: classref-method -|void| **erase_preset**\ (\ color\: :ref:`Color`\ ) +|void| **erase_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Removes the given color from the list of color presets of this color picker. @@ -521,7 +578,7 @@ Removes the given color from the list of color presets of this color picker. .. rst-class:: classref-method -|void| **erase_recent_preset**\ (\ color\: :ref:`Color`\ ) +|void| **erase_recent_preset**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Removes the given color from the list of color recent presets of this color picker. @@ -533,7 +590,7 @@ Removes the given color from the list of color recent presets of this color pick .. rst-class:: classref-method -:ref:`PackedColorArray` **get_presets**\ (\ ) |const| +:ref:`PackedColorArray` **get_presets**\ (\ ) |const| :ref:`🔗` Returns the list of colors in the presets of the color picker. @@ -545,7 +602,7 @@ Returns the list of colors in the presets of the color picker. .. rst-class:: classref-method -:ref:`PackedColorArray` **get_recent_presets**\ (\ ) |const| +:ref:`PackedColorArray` **get_recent_presets**\ (\ ) |const| :ref:`🔗` Returns the list of colors in the recent presets of the color picker. @@ -558,11 +615,23 @@ Returns the list of colors in the recent presets of the color picker. Theme Property Descriptions --------------------------- +.. _class_ColorPicker_theme_color_focused_not_editing_cursor_color: + +.. rst-class:: classref-themeproperty + +:ref:`Color` **focused_not_editing_cursor_color** = ``Color(1, 1, 1, 0.275)`` :ref:`🔗` + +Color of rectangle or circle drawn when a picker shape part is focused but not editable via keyboard or joypad. Displayed *over* the picker shape, so a partially transparent color should be used to ensure the picker shape remains visible. + +.. rst-class:: classref-item-separator + +---- + .. _class_ColorPicker_theme_constant_center_slider_grabbers: .. rst-class:: classref-themeproperty -:ref:`int` **center_slider_grabbers** = ``1`` +:ref:`int` **center_slider_grabbers** = ``1`` :ref:`🔗` Overrides the :ref:`Slider.center_grabber` theme property of the sliders. @@ -574,7 +643,7 @@ Overrides the :ref:`Slider.center_grabber` **h_width** = ``30`` +:ref:`int` **h_width** = ``30`` :ref:`🔗` The width of the hue selection slider. @@ -586,7 +655,7 @@ The width of the hue selection slider. .. rst-class:: classref-themeproperty -:ref:`int` **label_width** = ``10`` +:ref:`int` **label_width** = ``10`` :ref:`🔗` The minimum width of the color labels next to sliders. @@ -598,7 +667,7 @@ The minimum width of the color labels next to sliders. .. rst-class:: classref-themeproperty -:ref:`int` **margin** = ``4`` +:ref:`int` **margin** = ``4`` :ref:`🔗` The margin around the **ColorPicker**. @@ -610,7 +679,7 @@ The margin around the **ColorPicker**. .. rst-class:: classref-themeproperty -:ref:`int` **sv_height** = ``256`` +:ref:`int` **sv_height** = ``256`` :ref:`🔗` The height of the saturation-value selection box. @@ -622,7 +691,7 @@ The height of the saturation-value selection box. .. rst-class:: classref-themeproperty -:ref:`int` **sv_width** = ``256`` +:ref:`int` **sv_width** = ``256`` :ref:`🔗` The width of the saturation-value selection box. @@ -634,7 +703,7 @@ The width of the saturation-value selection box. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **add_preset** +:ref:`Texture2D` **add_preset** :ref:`🔗` The icon for the "Add Preset" button. @@ -646,7 +715,7 @@ The icon for the "Add Preset" button. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **bar_arrow** +:ref:`Texture2D` **bar_arrow** :ref:`🔗` The texture for the arrow grabber. @@ -658,7 +727,7 @@ The texture for the arrow grabber. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **color_hue** +:ref:`Texture2D` **color_hue** :ref:`🔗` Custom texture for the hue selection slider on the right. @@ -666,13 +735,13 @@ Custom texture for the hue selection slider on the right. ---- -.. _class_ColorPicker_theme_icon_color_okhsl_hue: +.. _class_ColorPicker_theme_icon_color_script: .. rst-class:: classref-themeproperty -:ref:`Texture2D` **color_okhsl_hue** +:ref:`Texture2D` **color_script** :ref:`🔗` -Custom texture for the H slider in the OKHSL color mode. +The icon for the button that switches color text to hexadecimal. .. rst-class:: classref-item-separator @@ -682,7 +751,7 @@ Custom texture for the H slider in the OKHSL color mode. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **expanded_arrow** +:ref:`Texture2D` **expanded_arrow** :ref:`🔗` The icon for color preset drop down menu when expanded. @@ -694,7 +763,7 @@ The icon for color preset drop down menu when expanded. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **folded_arrow** +:ref:`Texture2D` **folded_arrow** :ref:`🔗` The icon for color preset drop down menu when folded. @@ -702,11 +771,23 @@ The icon for color preset drop down menu when folded. ---- +.. _class_ColorPicker_theme_icon_menu_option: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **menu_option** :ref:`🔗` + +The icon for color preset option menu. + +.. rst-class:: classref-item-separator + +---- + .. _class_ColorPicker_theme_icon_overbright_indicator: .. rst-class:: classref-themeproperty -:ref:`Texture2D` **overbright_indicator** +:ref:`Texture2D` **overbright_indicator** :ref:`🔗` The indicator used to signalize that the color value is outside the 0-1 range. @@ -718,7 +799,7 @@ The indicator used to signalize that the color value is outside the 0-1 range. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **picker_cursor** +:ref:`Texture2D` **picker_cursor** :ref:`🔗` The image displayed over the color box/circle (depending on the :ref:`picker_shape`), marking the currently selected color. @@ -726,11 +807,23 @@ The image displayed over the color box/circle (depending on the :ref:`picker_sha ---- +.. _class_ColorPicker_theme_icon_picker_cursor_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **picker_cursor_bg** :ref:`🔗` + +The fill image displayed behind the picker cursor. + +.. rst-class:: classref-item-separator + +---- + .. _class_ColorPicker_theme_icon_sample_bg: .. rst-class:: classref-themeproperty -:ref:`Texture2D` **sample_bg** +:ref:`Texture2D` **sample_bg** :ref:`🔗` Background panel for the color preview box (visible when the color is translucent). @@ -742,7 +835,7 @@ Background panel for the color preview box (visible when the color is translucen .. rst-class:: classref-themeproperty -:ref:`Texture2D` **sample_revert** +:ref:`Texture2D` **sample_revert** :ref:`🔗` The icon for the revert button (visible on the middle of the "old" color when it differs from the currently selected color). This icon is modulated with a dark color if the "old" color is bright enough, so the icon should be bright to ensure visibility in both scenarios. @@ -754,7 +847,7 @@ The icon for the revert button (visible on the middle of the "old" color when it .. rst-class:: classref-themeproperty -:ref:`Texture2D` **screen_picker** +:ref:`Texture2D` **screen_picker** :ref:`🔗` The icon for the screen color picker button. @@ -766,7 +859,7 @@ The icon for the screen color picker button. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **shape_circle** +:ref:`Texture2D` **shape_circle** :ref:`🔗` The icon for circular picker shapes. @@ -778,7 +871,7 @@ The icon for circular picker shapes. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **shape_rect** +:ref:`Texture2D` **shape_rect** :ref:`🔗` The icon for rectangular picker shapes. @@ -790,11 +883,48 @@ The icon for rectangular picker shapes. .. rst-class:: classref-themeproperty -:ref:`Texture2D` **shape_rect_wheel** +:ref:`Texture2D` **shape_rect_wheel** :ref:`🔗` The icon for rectangular wheel picker shapes. +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_style_picker_focus_circle: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **picker_focus_circle** :ref:`🔗` + +The :ref:`StyleBox` used when the circle-shaped part of the picker is focused. Displayed *over* the picker shape, so a partially transparent :ref:`StyleBox` should be used to ensure the picker shape remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_style_picker_focus_rectangle: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **picker_focus_rectangle** :ref:`🔗` + +The :ref:`StyleBox` used when the rectangle-shaped part of the picker is focused. Displayed *over* the picker shape, so a partially transparent :ref:`StyleBox` should be used to ensure the picker shape remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPicker_theme_style_sample_focus: + +.. rst-class:: classref-themeproperty + +:ref:`StyleBox` **sample_focus** :ref:`🔗` + +The :ref:`StyleBox` used for the old color sample part when it is focused. Displayed *over* the sample, so a partially transparent :ref:`StyleBox` should be used to ensure the picker shape remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_colorpickerbutton.rst b/classes/class_colorpickerbutton.rst index 4d83b4323e4..bc8f4e5326e 100644 --- a/classes/class_colorpickerbutton.rst +++ b/classes/class_colorpickerbutton.rst @@ -30,9 +30,9 @@ See also :ref:`BaseButton` which contains common properties an Tutorials --------- -- `GUI Drag And Drop Demo `__ +- `2D GD Paint Demo `__ -- `2D GD Paint Demo `__ +- `GUI Drag And Drop Demo `__ .. rst-class:: classref-reftable-group @@ -42,13 +42,15 @@ Properties .. table:: :widths: auto - +---------------------------+----------------------------------------------------------------+-------------------------------------------------------------------------------+ - | :ref:`Color` | :ref:`color` | ``Color(0, 0, 0, 1)`` | - +---------------------------+----------------------------------------------------------------+-------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`edit_alpha` | ``true`` | - +---------------------------+----------------------------------------------------------------+-------------------------------------------------------------------------------+ - | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | - +---------------------------+----------------------------------------------------------------+-------------------------------------------------------------------------------+ + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`color` | ``Color(0, 0, 0, 1)`` | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`edit_alpha` | ``true`` | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`edit_intensity` | ``true`` | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | + +---------------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -89,7 +91,7 @@ Signals .. rst-class:: classref-signal -**color_changed**\ (\ color\: :ref:`Color`\ ) +**color_changed**\ (\ color\: :ref:`Color`\ ) :ref:`🔗` Emitted when the color changes. @@ -101,7 +103,7 @@ Emitted when the color changes. .. rst-class:: classref-signal -**picker_created**\ (\ ) +**picker_created**\ (\ ) :ref:`🔗` Emitted when the :ref:`ColorPicker` is created (the button is pressed for the first time). @@ -113,7 +115,7 @@ Emitted when the :ref:`ColorPicker` is created (the button is .. rst-class:: classref-signal -**popup_closed**\ (\ ) +**popup_closed**\ (\ ) :ref:`🔗` Emitted when the :ref:`ColorPicker` is closed. @@ -130,7 +132,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Color` **color** = ``Color(0, 0, 0, 1)`` +:ref:`Color` **color** = ``Color(0, 0, 0, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -147,7 +149,7 @@ The currently selected color. .. rst-class:: classref-property -:ref:`bool` **edit_alpha** = ``true`` +:ref:`bool` **edit_alpha** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -156,6 +158,23 @@ The currently selected color. If ``true``, the alpha channel in the displayed :ref:`ColorPicker` will be visible. +.. rst-class:: classref-item-separator + +---- + +.. _class_ColorPickerButton_property_edit_intensity: + +.. rst-class:: classref-property + +:ref:`bool` **edit_intensity** = ``true`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_edit_intensity**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_editing_intensity**\ (\ ) + +If ``true``, the intensity slider in the displayed :ref:`ColorPicker` will be visible. + .. rst-class:: classref-section-separator ---- @@ -169,7 +188,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`ColorPicker` **get_picker**\ (\ ) +:ref:`ColorPicker` **get_picker**\ (\ ) :ref:`🔗` Returns the :ref:`ColorPicker` that this node toggles. @@ -183,7 +202,7 @@ Returns the :ref:`ColorPicker` that this node toggles. .. rst-class:: classref-method -:ref:`PopupPanel` **get_popup**\ (\ ) +:ref:`PopupPanel` **get_popup**\ (\ ) :ref:`🔗` Returns the control's :ref:`PopupPanel` which allows you to connect to popup signals. This allows you to handle events when the ColorPicker is shown or hidden. @@ -202,11 +221,12 @@ Theme Property Descriptions .. rst-class:: classref-themeproperty -:ref:`Texture2D` **bg** +:ref:`Texture2D` **bg** :ref:`🔗` The background of the color preview rect on the button. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_colorrect.rst b/classes/class_colorrect.rst index b88adb12d76..aa2994f9b89 100644 --- a/classes/class_colorrect.rst +++ b/classes/class_colorrect.rst @@ -26,7 +26,7 @@ Displays a rectangle filled with a solid :ref:`color`__ +- `2D Dodge The Creeps Demo `__ .. rst-class:: classref-reftable-group @@ -53,7 +53,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` +:ref:`Color` **color** = ``Color(1, 1, 1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -63,6 +63,7 @@ Property Descriptions The fill color of the rectangle. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compositor.rst b/classes/class_compositor.rst index e0c83b9a7f0..17c99c06e0b 100644 --- a/classes/class_compositor.rst +++ b/classes/class_compositor.rst @@ -10,7 +10,7 @@ Compositor ========== -**Experimental:** More customisation of the rendering pipeline will be added in the future. +**Experimental:** More customization of the rendering pipeline will be added in the future. **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` @@ -23,6 +23,13 @@ Description The compositor resource stores attributes used to customize how a :ref:`Viewport` is rendered. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`The Compositor <../tutorials/rendering/compositor>` + .. rst-class:: classref-reftable-group Properties @@ -48,7 +55,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`Array`\[:ref:`CompositorEffect`\] **compositor_effects** = ``[]`` +:ref:`Array`\[:ref:`CompositorEffect`\] **compositor_effects** = ``[]`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -58,6 +65,7 @@ Property Descriptions The custom :ref:`CompositorEffect`\ s that are applied during rendering of viewports using this compositor. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compositoreffect.rst b/classes/class_compositoreffect.rst index bbc7dbf0b5f..8a28c052053 100644 --- a/classes/class_compositoreffect.rst +++ b/classes/class_compositoreffect.rst @@ -21,7 +21,14 @@ This resource allows for creating a custom rendering effect. Description ----------- -This resource defines a custom rendering effect that can be applied to :ref:`Viewport`\ s through the viewports' :ref:`Environment`. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. +This resource defines a custom rendering effect that can be applied to :ref:`Viewport`\ s through the viewports' :ref:`Environment`. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic. + +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`The Compositor <../tutorials/rendering/compositor>` .. rst-class:: classref-reftable-group @@ -72,7 +79,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **EffectCallbackType**: +enum **EffectCallbackType**: :ref:`🔗` .. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_PRE_OPAQUE: @@ -112,7 +119,7 @@ The callback is called before our transparent rendering pass, but after our sky :ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_POST_TRANSPARENT** = ``4`` -The callback is called after our transparent rendering pass, but before any build in post effects and output to our render target. +The callback is called after our transparent rendering pass, but before any built-in post-processing effects and output to our render target. .. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_MAX: @@ -135,7 +142,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **access_resolved_color** +:ref:`bool` **access_resolved_color** :ref:`🔗` .. rst-class:: classref-property-setget @@ -144,11 +151,11 @@ Property Descriptions If ``true`` and MSAA is enabled, this will trigger a color buffer resolve before the effect is run. -\ **Note:** In :ref:`_render_callback`, to access the resolved buffer use: +\ **Note:** In :ref:`_render_callback()`, to access the resolved buffer use: :: - var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var render_scene_buffers = render_data.get_render_scene_buffers() var color_buffer = render_scene_buffers.get_texture("render_buffers", "color") .. rst-class:: classref-item-separator @@ -159,7 +166,7 @@ If ``true`` and MSAA is enabled, this will trigger a color buffer resolve before .. rst-class:: classref-property -:ref:`bool` **access_resolved_depth** +:ref:`bool` **access_resolved_depth** :ref:`🔗` .. rst-class:: classref-property-setget @@ -168,11 +175,11 @@ If ``true`` and MSAA is enabled, this will trigger a color buffer resolve before If ``true`` and MSAA is enabled, this will trigger a depth buffer resolve before the effect is run. -\ **Note:** In :ref:`_render_callback`, to access the resolved buffer use: +\ **Note:** In :ref:`_render_callback()`, to access the resolved buffer use: :: - var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var render_scene_buffers = render_data.get_render_scene_buffers() var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth") .. rst-class:: classref-item-separator @@ -183,7 +190,7 @@ If ``true`` and MSAA is enabled, this will trigger a depth buffer resolve before .. rst-class:: classref-property -:ref:`EffectCallbackType` **effect_callback_type** +:ref:`EffectCallbackType` **effect_callback_type** :ref:`🔗` .. rst-class:: classref-property-setget @@ -200,7 +207,7 @@ The type of effect that is implemented, determines at what stage of rendering th .. rst-class:: classref-property -:ref:`bool` **enabled** +:ref:`bool` **enabled** :ref:`🔗` .. rst-class:: classref-property-setget @@ -217,7 +224,7 @@ If ``true`` this rendering effect is applied to any viewport it is added to. .. rst-class:: classref-property -:ref:`bool` **needs_motion_vectors** +:ref:`bool` **needs_motion_vectors** :ref:`🔗` .. rst-class:: classref-property-setget @@ -226,11 +233,11 @@ If ``true`` this rendering effect is applied to any viewport it is added to. If ``true`` this triggers motion vectors being calculated during the opaque render state. -\ **Note:** In :ref:`_render_callback`, to access the motion vector buffer use: +\ **Note:** In :ref:`_render_callback()`, to access the motion vector buffer use: :: - var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var render_scene_buffers = render_data.get_render_scene_buffers() var motion_buffer = render_scene_buffers.get_velocity_texture() .. rst-class:: classref-item-separator @@ -241,7 +248,7 @@ If ``true`` this triggers motion vectors being calculated during the opaque rend .. rst-class:: classref-property -:ref:`bool` **needs_normal_roughness** +:ref:`bool` **needs_normal_roughness** :ref:`🔗` .. rst-class:: classref-property-setget @@ -250,13 +257,26 @@ If ``true`` this triggers motion vectors being calculated during the opaque rend If ``true`` this triggers normal and roughness data to be output during our depth pre-pass, only applicable for the Forward+ renderer. -\ **Note:** In :ref:`_render_callback`, to access the roughness buffer use: +\ **Note:** In :ref:`_render_callback()`, to access the roughness buffer use: :: - var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() + var render_scene_buffers = render_data.get_render_scene_buffers() var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness") +The raw normal and roughness buffer is stored in an optimized format, different than the one available in Spatial shaders. When sampling the buffer, a conversion function must be applied. Use this function, copied from `here `__: + +:: + + vec4 normal_roughness_compatibility(vec4 p_normal_roughness) { + float roughness = p_normal_roughness.w; + if (roughness > 0.5) { + roughness = 1.0 - roughness; + } + roughness /= (127.0 / 255.0); + return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness); + } + .. rst-class:: classref-item-separator ---- @@ -265,7 +285,7 @@ If ``true`` this triggers normal and roughness data to be output during our dept .. rst-class:: classref-property -:ref:`bool` **needs_separate_specular** +:ref:`bool` **needs_separate_specular** :ref:`🔗` .. rst-class:: classref-property-setget @@ -287,11 +307,12 @@ Method Descriptions .. rst-class:: classref-method -|void| **_render_callback**\ (\ effect_callback_type\: :ref:`int`, render_data\: :ref:`RenderData`\ ) |virtual| +|void| **_render_callback**\ (\ effect_callback_type\: :ref:`int`, render_data\: :ref:`RenderData`\ ) |virtual| :ref:`🔗` Implement this function with your custom rendering code. ``effect_callback_type`` should always match the effect callback type you've specified in :ref:`effect_callback_type`. ``render_data`` provides access to the rendering state, it is only valid during rendering and should not be stored. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compressedcubemap.rst b/classes/class_compressedcubemap.rst index 8efe7d06a25..499f85aa779 100644 --- a/classes/class_compressedcubemap.rst +++ b/classes/class_compressedcubemap.rst @@ -38,6 +38,7 @@ Using **VRAM Compressed** also improves loading times, as VRAM-compressed textur See :ref:`Cubemap` for a general description of cubemaps. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compressedcubemaparray.rst b/classes/class_compressedcubemaparray.rst index 71b3fd5fce6..59df932dc2f 100644 --- a/classes/class_compressedcubemaparray.rst +++ b/classes/class_compressedcubemaparray.rst @@ -38,6 +38,7 @@ Using **VRAM Compressed** also improves loading times, as VRAM-compressed textur See :ref:`CubemapArray` for a general description of cubemap arrays. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compressedtexture2d.rst b/classes/class_compressedtexture2d.rst index d9ffa1cf611..7f8356fff89 100644 --- a/classes/class_compressedtexture2d.rst +++ b/classes/class_compressedtexture2d.rst @@ -74,7 +74,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`String` **load_path** = ``""`` +:ref:`String` **load_path** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -96,11 +96,12 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` Loads the texture from the specified ``path``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compressedtexture2darray.rst b/classes/class_compressedtexture2darray.rst index 7ea9a4de684..2142a4ded4a 100644 --- a/classes/class_compressedtexture2darray.rst +++ b/classes/class_compressedtexture2darray.rst @@ -38,6 +38,7 @@ Using **VRAM Compressed** also improves loading times, as VRAM-compressed textur See :ref:`Texture2DArray` for a general description of texture arrays. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compressedtexture3d.rst b/classes/class_compressedtexture3d.rst index b88c5a1bb3c..32c06648ed9 100644 --- a/classes/class_compressedtexture3d.rst +++ b/classes/class_compressedtexture3d.rst @@ -62,7 +62,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`String` **load_path** = ``""`` +:ref:`String` **load_path** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -84,11 +84,12 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` Loads the texture from the specified ``path``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_compressedtexturelayered.rst b/classes/class_compressedtexturelayered.rst index f14ef46aeee..463666444de 100644 --- a/classes/class_compressedtexturelayered.rst +++ b/classes/class_compressedtexturelayered.rst @@ -60,7 +60,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`String` **load_path** = ``""`` +:ref:`String` **load_path** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -82,11 +82,12 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` Loads the texture at ``path``. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_concavepolygonshape2d.rst b/classes/class_concavepolygonshape2d.rst index e97183b52a1..354a22c88dc 100644 --- a/classes/class_concavepolygonshape2d.rst +++ b/classes/class_concavepolygonshape2d.rst @@ -54,7 +54,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`PackedVector2Array` **segments** = ``PackedVector2Array()`` +:ref:`PackedVector2Array` **segments** = ``PackedVector2Array()`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -63,7 +63,10 @@ Property Descriptions The array of points that make up the **ConcavePolygonShape2D**'s line segments. The array (of length divisible by two) is naturally divided into pairs (one pair for each segment); each pair consists of the starting point of a segment and the endpoint of a segment. +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedVector2Array` for more details. + .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_concavepolygonshape3d.rst b/classes/class_concavepolygonshape3d.rst index 898385d056d..e4d8714396d 100644 --- a/classes/class_concavepolygonshape3d.rst +++ b/classes/class_concavepolygonshape3d.rst @@ -34,7 +34,7 @@ Being just a collection of interconnected triangles, **ConcavePolygonShape3D** i Tutorials --------- -- `3D Physics Tests Demo `__ +- `3D Physics Tests Demo `__ .. rst-class:: classref-reftable-group @@ -75,7 +75,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`bool` **backface_collision** = ``false`` +:ref:`bool` **backface_collision** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -97,7 +97,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`PackedVector3Array` **get_faces**\ (\ ) |const| +:ref:`PackedVector3Array` **get_faces**\ (\ ) |const| :ref:`🔗` Returns the faces of the trimesh shape as an array of vertices. The array (of length divisible by three) is naturally divided into triples; each triple of vertices defines a triangle. @@ -109,11 +109,12 @@ Returns the faces of the trimesh shape as an array of vertices. The array (of le .. rst-class:: classref-method -|void| **set_faces**\ (\ faces\: :ref:`PackedVector3Array`\ ) +|void| **set_faces**\ (\ faces\: :ref:`PackedVector3Array`\ ) :ref:`🔗` Sets the faces of the trimesh shape from an array of vertices. The ``faces`` array should be composed of triples such that each triple of vertices defines a triangle. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_conetwistjoint3d.rst b/classes/class_conetwistjoint3d.rst index 079ca1eb9b3..044a00bb9a2 100644 --- a/classes/class_conetwistjoint3d.rst +++ b/classes/class_conetwistjoint3d.rst @@ -29,17 +29,17 @@ Properties .. table:: :widths: auto - +---------------------------+---------------------------------------------------------------+--------------+ - | :ref:`float` | :ref:`bias` | ``0.3`` | - +---------------------------+---------------------------------------------------------------+--------------+ - | :ref:`float` | :ref:`relaxation` | ``1.0`` | - +---------------------------+---------------------------------------------------------------+--------------+ - | :ref:`float` | :ref:`softness` | ``0.8`` | - +---------------------------+---------------------------------------------------------------+--------------+ - | :ref:`float` | :ref:`swing_span` | ``0.785398`` | - +---------------------------+---------------------------------------------------------------+--------------+ - | :ref:`float` | :ref:`twist_span` | ``3.14159`` | - +---------------------------+---------------------------------------------------------------+--------------+ + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`bias` | ``0.3`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`relaxation` | ``1.0`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`softness` | ``0.8`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`swing_span` | ``0.7853982`` | + +---------------------------+---------------------------------------------------------------+---------------+ + | :ref:`float` | :ref:`twist_span` | ``3.1415927`` | + +---------------------------+---------------------------------------------------------------+---------------+ .. rst-class:: classref-reftable-group @@ -68,7 +68,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **Param**: +enum **Param**: :ref:`🔗` .. _class_ConeTwistJoint3D_constant_PARAM_SWING_SPAN: @@ -141,7 +141,7 @@ Property Descriptions .. rst-class:: classref-property -:ref:`float` **bias** = ``0.3`` +:ref:`float` **bias** = ``0.3`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -160,7 +160,7 @@ The higher, the faster. .. rst-class:: classref-property -:ref:`float` **relaxation** = ``1.0`` +:ref:`float` **relaxation** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -177,7 +177,7 @@ Defines, how fast the swing- and twist-speed-difference on both sides gets synce .. rst-class:: classref-property -:ref:`float` **softness** = ``0.8`` +:ref:`float` **softness** = ``0.8`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -194,7 +194,7 @@ The ease with which the joint starts to twist. If it's too low, it takes more fo .. rst-class:: classref-property -:ref:`float` **swing_span** = ``0.785398`` +:ref:`float` **swing_span** = ``0.7853982`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -217,7 +217,7 @@ If below 0.05, this behavior is locked. .. rst-class:: classref-property -:ref:`float` **twist_span** = ``3.14159`` +:ref:`float` **twist_span** = ``3.1415927`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -241,7 +241,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| +:ref:`float` **get_param**\ (\ param\: :ref:`Param`\ ) |const| :ref:`🔗` Returns the value of the specified parameter. @@ -253,11 +253,12 @@ Returns the value of the specified parameter. .. rst-class:: classref-method -|void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) +|void| **set_param**\ (\ param\: :ref:`Param`, value\: :ref:`float`\ ) :ref:`🔗` Sets the value of the specified parameter. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_configfile.rst b/classes/class_configfile.rst index 212f0415dbe..5925b35cc54 100644 --- a/classes/class_configfile.rst +++ b/classes/class_configfile.rst @@ -21,7 +21,7 @@ Description This helper class can be used to store :ref:`Variant` values on the filesystem using INI-style formatting. The stored values are identified by a section and a key: -:: +.. code:: text [section] some_key=42 @@ -39,13 +39,13 @@ The following example shows how to create a simple **ConfigFile** and save it on # Create new ConfigFile object. var config = ConfigFile.new() - + # Store some values. config.set_value("Player1", "player_name", "Steve") config.set_value("Player1", "best_score", 10) config.set_value("Player2", "player_name", "V3geta") config.set_value("Player2", "best_score", 9001) - + # Save it to a file (overwrite if already exists). config.save("user://scores.cfg") @@ -53,13 +53,13 @@ The following example shows how to create a simple **ConfigFile** and save it on // Create new ConfigFile object. var config = new ConfigFile(); - + // Store some values. config.SetValue("Player1", "player_name", "Steve"); config.SetValue("Player1", "best_score", 10); config.SetValue("Player2", "player_name", "V3geta"); config.SetValue("Player2", "best_score", 9001); - + // Save it to a file (overwrite if already exists). config.Save("user://scores.cfg"); @@ -74,14 +74,14 @@ This example shows how the above file could be loaded: var score_data = {} var config = ConfigFile.new() - + # Load data from a file. var err = config.load("user://scores.cfg") - + # If the file didn't load, ignore it. if err != OK: return - + # Iterate over all sections. for player in config.get_sections(): # Fetch the data for each section. @@ -93,16 +93,16 @@ This example shows how the above file could be loaded: var score_data = new Godot.Collections.Dictionary(); var config = new ConfigFile(); - + // Load data from a file. Error err = config.Load("user://scores.cfg"); - + // If the file didn't load, ignore it. if (err != Error.Ok) { return; } - + // Iterate over all sections. foreach (String player in config.GetSections()) { @@ -114,7 +114,7 @@ This example shows how the above file could be loaded: -Any operation that mutates the ConfigFile such as :ref:`set_value`, :ref:`clear`, or :ref:`erase_section`, only changes what is loaded in memory. If you want to write the change to a file, you have to save the changes with :ref:`save`, :ref:`save_encrypted`, or :ref:`save_encrypted_pass`. +Any operation that mutates the ConfigFile such as :ref:`set_value()`, :ref:`clear()`, or :ref:`erase_section()`, only changes what is loaded in memory. If you want to write the change to a file, you have to save the changes with :ref:`save()`, :ref:`save_encrypted()`, or :ref:`save_encrypted_pass()`. Keep in mind that section and property names can't contain spaces. Anything after a space will be ignored on save and on load. @@ -179,7 +179,7 @@ Method Descriptions .. rst-class:: classref-method -|void| **clear**\ (\ ) +|void| **clear**\ (\ ) :ref:`🔗` Removes the entire contents of the config. @@ -191,7 +191,7 @@ Removes the entire contents of the config. .. rst-class:: classref-method -:ref:`String` **encode_to_text**\ (\ ) |const| +:ref:`String` **encode_to_text**\ (\ ) |const| :ref:`🔗` Obtain the text version of this config file (the same text that would be written to a file). @@ -203,7 +203,7 @@ Obtain the text version of this config file (the same text that would be written .. rst-class:: classref-method -|void| **erase_section**\ (\ section\: :ref:`String`\ ) +|void| **erase_section**\ (\ section\: :ref:`String`\ ) :ref:`🔗` Deletes the specified section along with all the key-value pairs inside. Raises an error if the section does not exist. @@ -215,7 +215,7 @@ Deletes the specified section along with all the key-value pairs inside. Raises .. rst-class:: classref-method -|void| **erase_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) +|void| **erase_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) :ref:`🔗` Deletes the specified key in a section. Raises an error if either the section or the key do not exist. @@ -227,7 +227,7 @@ Deletes the specified key in a section. Raises an error if either the section or .. rst-class:: classref-method -:ref:`PackedStringArray` **get_section_keys**\ (\ section\: :ref:`String`\ ) |const| +:ref:`PackedStringArray` **get_section_keys**\ (\ section\: :ref:`String`\ ) |const| :ref:`🔗` Returns an array of all defined key identifiers in the specified section. Raises an error and returns an empty array if the section does not exist. @@ -239,7 +239,7 @@ Returns an array of all defined key identifiers in the specified section. Raises .. rst-class:: classref-method -:ref:`PackedStringArray` **get_sections**\ (\ ) |const| +:ref:`PackedStringArray` **get_sections**\ (\ ) |const| :ref:`🔗` Returns an array of all defined section identifiers. @@ -251,7 +251,7 @@ Returns an array of all defined section identifiers. .. rst-class:: classref-method -:ref:`Variant` **get_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, default\: :ref:`Variant` = null\ ) |const| +:ref:`Variant` **get_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, default\: :ref:`Variant` = null\ ) |const| :ref:`🔗` Returns the current value for the specified section and key. If either the section or the key do not exist, the method returns the fallback ``default`` value. If ``default`` is not specified or set to ``null``, an error is also raised. @@ -263,7 +263,7 @@ Returns the current value for the specified section and key. If either the secti .. rst-class:: classref-method -:ref:`bool` **has_section**\ (\ section\: :ref:`String`\ ) |const| +:ref:`bool` **has_section**\ (\ section\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the specified section exists. @@ -275,7 +275,7 @@ Returns ``true`` if the specified section exists. .. rst-class:: classref-method -:ref:`bool` **has_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) |const| +:ref:`bool` **has_section_key**\ (\ section\: :ref:`String`, key\: :ref:`String`\ ) |const| :ref:`🔗` Returns ``true`` if the specified section-key pair exists. @@ -287,7 +287,7 @@ Returns ``true`` if the specified section-key pair exists. .. rst-class:: classref-method -:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) +:ref:`Error` **load**\ (\ path\: :ref:`String`\ ) :ref:`🔗` Loads the config file specified as a parameter. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. @@ -301,7 +301,7 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -:ref:`Error` **load_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) +:ref:`Error` **load_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) :ref:`🔗` Loads the encrypted config file specified as a parameter, using the provided ``key`` to decrypt it. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. @@ -315,7 +315,7 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -:ref:`Error` **load_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) +:ref:`Error` **load_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) :ref:`🔗` Loads the encrypted config file specified as a parameter, using the provided ``password`` to decrypt it. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. @@ -329,7 +329,7 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -:ref:`Error` **parse**\ (\ data\: :ref:`String`\ ) +:ref:`Error` **parse**\ (\ data\: :ref:`String`\ ) :ref:`🔗` Parses the passed string as the contents of a config file. The string is parsed and loaded in the ConfigFile object which the method was called on. @@ -343,7 +343,7 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -:ref:`Error` **save**\ (\ path\: :ref:`String`\ ) +:ref:`Error` **save**\ (\ path\: :ref:`String`\ ) :ref:`🔗` Saves the contents of the **ConfigFile** object to the file specified as a parameter. The output file uses an INI-style structure. @@ -357,7 +357,7 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -:ref:`Error` **save_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) +:ref:`Error` **save_encrypted**\ (\ path\: :ref:`String`, key\: :ref:`PackedByteArray`\ ) :ref:`🔗` Saves the contents of the **ConfigFile** object to the AES-256 encrypted file specified as a parameter, using the provided ``key`` to encrypt it. The output file uses an INI-style structure. @@ -371,7 +371,7 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -:ref:`Error` **save_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) +:ref:`Error` **save_encrypted_pass**\ (\ path\: :ref:`String`, password\: :ref:`String`\ ) :ref:`🔗` Saves the contents of the **ConfigFile** object to the AES-256 encrypted file specified as a parameter, using the provided ``password`` to encrypt it. The output file uses an INI-style structure. @@ -385,11 +385,12 @@ Returns :ref:`@GlobalScope.OK` on success, or on .. rst-class:: classref-method -|void| **set_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, value\: :ref:`Variant`\ ) +|void| **set_value**\ (\ section\: :ref:`String`, key\: :ref:`String`, value\: :ref:`Variant`\ ) :ref:`🔗` Assigns a value to the specified key of the specified section. If either the section or the key do not exist, they are created. Passing a ``null`` value deletes the specified key if it exists, and deletes the section if it ends up empty once the key has been removed. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_confirmationdialog.rst b/classes/class_confirmationdialog.rst index 16e1c04761a..cc06c41a2e2 100644 --- a/classes/class_confirmationdialog.rst +++ b/classes/class_confirmationdialog.rst @@ -30,11 +30,11 @@ To get cancel action, you can use: .. code-tab:: gdscript - get_cancel_button().pressed.connect(self.canceled) + get_cancel_button().pressed.connect(_on_canceled) .. code-tab:: csharp - GetCancelButton().Pressed += Canceled; + GetCancelButton().Pressed += OnCanceled; @@ -81,14 +81,14 @@ Property Descriptions .. rst-class:: classref-property -:ref:`String` **cancel_button_text** = ``"Cancel"`` +:ref:`String` **cancel_button_text** = ``"Cancel"`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_cancel_button_text**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_cancel_button_text**\ (\ ) -The text displayed by the cancel button (see :ref:`get_cancel_button`). +The text displayed by the cancel button (see :ref:`get_cancel_button()`). .. rst-class:: classref-section-separator @@ -103,13 +103,14 @@ Method Descriptions .. rst-class:: classref-method -:ref:`Button` **get_cancel_button**\ (\ ) +:ref:`Button` **get_cancel_button**\ (\ ) :ref:`🔗` Returns the cancel button. \ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible` property. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_container.rst b/classes/class_container.rst index f8ea36cad8b..7aa4d835398 100644 --- a/classes/class_container.rst +++ b/classes/class_container.rst @@ -12,7 +12,7 @@ Container **Inherits:** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` -**Inherited By:** :ref:`AspectRatioContainer`, :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`FlowContainer`, :ref:`GraphElement`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`SubViewportContainer`, :ref:`TabContainer` +**Inherited By:** :ref:`AspectRatioContainer`, :ref:`BoxContainer`, :ref:`CenterContainer`, :ref:`EditorProperty`, :ref:`FlowContainer`, :ref:`FoldableContainer`, :ref:`GraphElement`, :ref:`GridContainer`, :ref:`MarginContainer`, :ref:`PanelContainer`, :ref:`ScrollContainer`, :ref:`SplitContainer`, :ref:`SubViewportContainer`, :ref:`TabContainer` Base class for all GUI containers. @@ -73,7 +73,7 @@ Signals .. rst-class:: classref-signal -**pre_sort_children**\ (\ ) +**pre_sort_children**\ (\ ) :ref:`🔗` Emitted when children are going to be sorted. @@ -85,7 +85,7 @@ Emitted when children are going to be sorted. .. rst-class:: classref-signal -**sort_children**\ (\ ) +**sort_children**\ (\ ) :ref:`🔗` Emitted when sorting the children is needed. @@ -102,7 +102,7 @@ Constants .. rst-class:: classref-constant -**NOTIFICATION_PRE_SORT_CHILDREN** = ``50`` +**NOTIFICATION_PRE_SORT_CHILDREN** = ``50`` :ref:`🔗` Notification just before children are going to be sorted, in case there's something to process beforehand. @@ -110,7 +110,7 @@ Notification just before children are going to be sorted, in case there's someth .. rst-class:: classref-constant -**NOTIFICATION_SORT_CHILDREN** = ``51`` +**NOTIFICATION_SORT_CHILDREN** = ``51`` :ref:`🔗` Notification for when sorting the children, it must be obeyed immediately. @@ -127,7 +127,7 @@ Method Descriptions .. rst-class:: classref-method -:ref:`PackedInt32Array` **_get_allowed_size_flags_horizontal**\ (\ ) |virtual| |const| +:ref:`PackedInt32Array` **_get_allowed_size_flags_horizontal**\ (\ ) |virtual| |const| :ref:`🔗` Implement to return a list of allowed horizontal :ref:`SizeFlags` for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the Inspector dock. @@ -141,7 +141,7 @@ Implement to return a list of allowed horizontal :ref:`SizeFlags` **_get_allowed_size_flags_vertical**\ (\ ) |virtual| |const| +:ref:`PackedInt32Array` **_get_allowed_size_flags_vertical**\ (\ ) |virtual| |const| :ref:`🔗` Implement to return a list of allowed vertical :ref:`SizeFlags` for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the Inspector dock. @@ -155,7 +155,7 @@ Implement to return a list of allowed vertical :ref:`SizeFlags`, rect\: :ref:`Rect2`\ ) +|void| **fit_child_in_rect**\ (\ child\: :ref:`Control`, rect\: :ref:`Rect2`\ ) :ref:`🔗` Fit a child control in a given rect. This is mainly a helper for creating custom container classes. @@ -167,11 +167,12 @@ Fit a child control in a given rect. This is mainly a helper for creating custom .. rst-class:: classref-method -|void| **queue_sort**\ (\ ) +|void| **queue_sort**\ (\ ) :ref:`🔗` Queue resort of the contained children. This is called automatically anyway, but can be called upon request. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` +.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |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.)` diff --git a/classes/class_control.rst b/classes/class_control.rst index 66c0ffb4d50..916ff59c863 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -25,21 +25,23 @@ Base class for all UI-related nodes. **Control** features a bounding rectangle t For more information on Godot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from **Control** and :ref:`Container` nodes. +\ **Note:** Since both :ref:`Node2D` and **Control** inherit from :ref:`CanvasItem`, they share several concepts from the class such as the :ref:`CanvasItem.z_index` and :ref:`CanvasItem.visible` properties. + \ **User Interface nodes and input**\ Godot propagates input events via viewports. Each :ref:`Viewport` is responsible for propagating :ref:`InputEvent`\ s to their child nodes. As the :ref:`SceneTree.root` is a :ref:`Window`, this already happens automatically for all UI elements in your game. -Input events are propagated through the :ref:`SceneTree` from the root node to all child nodes by calling :ref:`Node._input`. For UI elements specifically, it makes more sense to override the virtual method :ref:`_gui_input`, which filters out unrelated input events, such as by checking z-order, :ref:`mouse_filter`, focus, or if the event was inside of the control's bounding box. +Input events are propagated through the :ref:`SceneTree` from the root node to all child nodes by calling :ref:`Node._input()`. For UI elements specifically, it makes more sense to override the virtual method :ref:`_gui_input()`, which filters out unrelated input events, such as by checking z-order, :ref:`mouse_filter`, focus, or if the event was inside of the control's bounding box. -Call :ref:`accept_event` so no other node receives the event. Once you accept an input, it becomes handled so :ref:`Node._unhandled_input` will not process it. +Call :ref:`accept_event()` so no other node receives the event. Once you accept an input, it becomes handled so :ref:`Node._unhandled_input()` will not process it. -Only one **Control** node can be in focus. Only the node in focus will receive events. To get the focus, call :ref:`grab_focus`. **Control** nodes lose focus when another node grabs it, or if you hide the node in focus. +Only one **Control** node can be in focus. Only the node in focus will receive events. To get the focus, call :ref:`grab_focus()`. **Control** nodes lose focus when another node grabs it, or if you hide the node in focus. Sets :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` to tell a **Control** node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. -\ :ref:`Theme` resources change the Control's appearance. If you change the :ref:`Theme` on a **Control** node, it affects all of its children. To override some of the theme's parameters, call one of the ``add_theme_*_override`` methods, like :ref:`add_theme_font_override`. You can override the theme with the Inspector. +\ :ref:`Theme` resources change the control's appearance. The :ref:`theme` of a **Control** node affects all of its direct and indirect children (as long as a chain of controls is uninterrupted). To override some of the theme items, call one of the ``add_theme_*_override`` methods, like :ref:`add_theme_font_override()`. You can also override theme items in the Inspector. -\ **Note:** Theme items are *not* :ref:`Object` properties. This means you can't access their values using :ref:`Object.get` and :ref:`Object.set`. Instead, use the ``get_theme_*`` and ``add_theme_*_override`` methods provided by this class. +\ **Note:** Theme items are *not* :ref:`Object` properties. This means you can't access their values using :ref:`Object.get()` and :ref:`Object.set()`. Instead, use the ``get_theme_*`` and ``add_theme_*_override`` methods provided by this class. .. rst-class:: classref-introduction-group @@ -64,85 +66,107 @@ Properties .. table:: :widths: auto - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`anchor_bottom` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`anchor_left` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`anchor_right` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`anchor_top` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`bool` | :ref:`auto_translate` | ``true`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`bool` | :ref:`clip_contents` | ``false`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Vector2` | :ref:`custom_minimum_size` | ``Vector2(0, 0)`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`FocusMode` | :ref:`focus_mode` | ``0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`NodePath` | :ref:`focus_neighbor_bottom` | ``NodePath("")`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`NodePath` | :ref:`focus_neighbor_left` | ``NodePath("")`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`NodePath` | :ref:`focus_neighbor_right` | ``NodePath("")`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`NodePath` | :ref:`focus_neighbor_top` | ``NodePath("")`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`NodePath` | :ref:`focus_next` | ``NodePath("")`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`NodePath` | :ref:`focus_previous` | ``NodePath("")`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Vector2` | :ref:`global_position` | | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`GrowDirection` | :ref:`grow_horizontal` | ``1`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`GrowDirection` | :ref:`grow_vertical` | ``1`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`LayoutDirection` | :ref:`layout_direction` | ``0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`bool` | :ref:`localize_numeral_system` | ``true`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`CursorShape` | :ref:`mouse_default_cursor_shape` | ``0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`MouseFilter` | :ref:`mouse_filter` | ``0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`bool` | :ref:`mouse_force_pass_scroll_events` | ``true`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`offset_bottom` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`offset_left` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`offset_right` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`offset_top` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Vector2` | :ref:`pivot_offset` | ``Vector2(0, 0)`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Vector2` | :ref:`position` | ``Vector2(0, 0)`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`rotation` | ``0.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`rotation_degrees` | | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Vector2` | :ref:`scale` | ``Vector2(1, 1)`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Node` | :ref:`shortcut_context` | | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Vector2` | :ref:`size` | ``Vector2(0, 0)`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | |bitfield|\[:ref:`SizeFlags`\] | :ref:`size_flags_horizontal` | ``1`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`float` | :ref:`size_flags_stretch_ratio` | ``1.0`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | |bitfield|\[:ref:`SizeFlags`\] | :ref:`size_flags_vertical` | ``1`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`Theme` | :ref:`theme` | | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`StringName` | :ref:`theme_type_variation` | ``&""`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ - | :ref:`String` | :ref:`tooltip_text` | ``""`` | - +--------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------+ + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_controls_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_described_by_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`accessibility_description` | ``""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_flow_to_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`NodePath`\] | :ref:`accessibility_labeled_by_nodes` | ``[]`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`AccessibilityLiveMode` | :ref:`accessibility_live` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`accessibility_name` | ``""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_bottom` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_left` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_right` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`anchor_top` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`auto_translate` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`clip_contents` | ``false`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`custom_minimum_size` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`FocusBehaviorRecursive` | :ref:`focus_behavior_recursive` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`FocusMode` | :ref:`focus_mode` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_bottom` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_left` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_right` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_neighbor_top` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_next` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`focus_previous` | ``NodePath("")`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`global_position` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`GrowDirection` | :ref:`grow_horizontal` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`GrowDirection` | :ref:`grow_vertical` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`LayoutDirection` | :ref:`layout_direction` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`localize_numeral_system` | ``true`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`MouseBehaviorRecursive` | :ref:`mouse_behavior_recursive` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`CursorShape` | :ref:`mouse_default_cursor_shape` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`MouseFilter` | :ref:`mouse_filter` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`mouse_force_pass_scroll_events` | ``true`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_bottom` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_left` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_right` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`offset_top` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`PhysicsInterpolationMode` | physics_interpolation_mode | ``2`` (overrides :ref:`Node`) | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`pivot_offset` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`position` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rotation` | ``0.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`rotation_degrees` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`scale` | ``Vector2(1, 1)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Node` | :ref:`shortcut_context` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`size` | ``Vector2(0, 0)`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | |bitfield|\[:ref:`SizeFlags`\] | :ref:`size_flags_horizontal` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`size_flags_stretch_ratio` | ``1.0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | |bitfield|\[:ref:`SizeFlags`\] | :ref:`size_flags_vertical` | ``1`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`Theme` | :ref:`theme` | | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`theme_type_variation` | ``&""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`AutoTranslateMode` | :ref:`tooltip_auto_translate_mode` | ``0`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`tooltip_text` | ``""`` | + +------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ .. rst-class:: classref-reftable-group @@ -152,11 +176,15 @@ Methods .. table:: :widths: auto + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_accessibility_get_contextual_info`\ (\ ) |virtual| |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_can_drop_data`\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`_drop_data`\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`_get_accessibility_container_name`\ (\ node\: :ref:`Node`\ ) |virtual| |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`_get_drag_data`\ (\ at_position\: :ref:`Vector2`\ ) |virtual| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`_get_minimum_size`\ (\ ) |virtual| |const| | @@ -173,6 +201,10 @@ Methods +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`accept_event`\ (\ ) | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`accessibility_drag`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`accessibility_drop`\ (\ ) | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_theme_color_override`\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_theme_constant_override`\ (\ name\: :ref:`StringName`, constant\: :ref:`int`\ ) | @@ -207,12 +239,16 @@ Methods +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_end`\ (\ ) |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FocusMode` | :ref:`get_focus_mode_with_override`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`NodePath` | :ref:`get_focus_neighbor`\ (\ side\: :ref:`Side`\ ) |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Rect2` | :ref:`get_global_rect`\ (\ ) |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_minimum_size`\ (\ ) |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`MouseFilter` | :ref:`get_mouse_filter_with_override`\ (\ ) |const| | + +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_offset`\ (\ offset\: :ref:`Side`\ ) |const| | +--------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`get_parent_area_size`\ (\ ) |const| | @@ -339,7 +375,7 @@ Signals .. rst-class:: classref-signal -**focus_entered**\ (\ ) +**focus_entered**\ (\ ) :ref:`🔗` Emitted when the node gains focus. @@ -351,7 +387,7 @@ Emitted when the node gains focus. .. rst-class:: classref-signal -**focus_exited**\ (\ ) +**focus_exited**\ (\ ) :ref:`🔗` Emitted when the node loses focus. @@ -363,7 +399,7 @@ Emitted when the node loses focus. .. rst-class:: classref-signal -**gui_input**\ (\ event\: :ref:`InputEvent`\ ) +**gui_input**\ (\ event\: :ref:`InputEvent`\ ) :ref:`🔗` Emitted when the node receives an :ref:`InputEvent`. @@ -375,7 +411,7 @@ Emitted when the node receives an :ref:`InputEvent`. .. rst-class:: classref-signal -**minimum_size_changed**\ (\ ) +**minimum_size_changed**\ (\ ) :ref:`🔗` Emitted when the node's minimum size changes. @@ -387,7 +423,7 @@ Emitted when the node's minimum size changes. .. rst-class:: classref-signal -**mouse_entered**\ (\ ) +**mouse_entered**\ (\ ) :ref:`🔗` Emitted when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. @@ -401,7 +437,7 @@ Emitted when the mouse cursor enters the control's (or any child control's) visi .. rst-class:: classref-signal -**mouse_exited**\ (\ ) +**mouse_exited**\ (\ ) :ref:`🔗` Emitted when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. @@ -423,7 +459,7 @@ Emitted when the mouse cursor leaves the control's (and all child control's) vis .. rst-class:: classref-signal -**resized**\ (\ ) +**resized**\ (\ ) :ref:`🔗` Emitted when the control changes size. @@ -435,7 +471,7 @@ Emitted when the control changes size. .. rst-class:: classref-signal -**size_flags_changed**\ (\ ) +**size_flags_changed**\ (\ ) :ref:`🔗` Emitted when one of the size flags changes. See :ref:`size_flags_horizontal` and :ref:`size_flags_vertical`. @@ -447,7 +483,7 @@ Emitted when one of the size flags changes. See :ref:`size_flags_horizontal` Emitted when the :ref:`NOTIFICATION_THEME_CHANGED` notification is sent. @@ -464,7 +500,7 @@ Enumerations .. rst-class:: classref-enumeration -enum **FocusMode**: +enum **FocusMode**: :ref:`🔗` .. _class_Control_constant_FOCUS_NONE: @@ -490,6 +526,82 @@ The node can only grab focus on mouse clicks. Use with :ref:`focus_mode`. +.. _class_Control_constant_FOCUS_ACCESSIBILITY: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusMode` **FOCUS_ACCESSIBILITY** = ``3`` + +The node can grab focus only when screen reader is active. Use with :ref:`focus_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_FocusBehaviorRecursive: + +.. rst-class:: classref-enumeration + +enum **FocusBehaviorRecursive**: :ref:`🔗` + +.. _class_Control_constant_FOCUS_BEHAVIOR_INHERITED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusBehaviorRecursive` **FOCUS_BEHAVIOR_INHERITED** = ``0`` + +Inherits the :ref:`focus_behavior_recursive` from the parent control. If there is no parent control, this is the same as :ref:`FOCUS_BEHAVIOR_ENABLED`. + +.. _class_Control_constant_FOCUS_BEHAVIOR_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusBehaviorRecursive` **FOCUS_BEHAVIOR_DISABLED** = ``1`` + +Prevents the control from getting focused. :ref:`get_focus_mode_with_override()` will return :ref:`FOCUS_NONE`. + +.. _class_Control_constant_FOCUS_BEHAVIOR_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`FocusBehaviorRecursive` **FOCUS_BEHAVIOR_ENABLED** = ``2`` + +Allows the control to be focused, depending on the :ref:`focus_mode`. This can be used to ignore the parent's :ref:`focus_behavior_recursive`. :ref:`get_focus_mode_with_override()` will return the :ref:`focus_mode`. + +.. rst-class:: classref-item-separator + +---- + +.. _enum_Control_MouseBehaviorRecursive: + +.. rst-class:: classref-enumeration + +enum **MouseBehaviorRecursive**: :ref:`🔗` + +.. _class_Control_constant_MOUSE_BEHAVIOR_INHERITED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseBehaviorRecursive` **MOUSE_BEHAVIOR_INHERITED** = ``0`` + +Inherits the :ref:`mouse_behavior_recursive` from the parent control. If there is no parent control, this is the same as :ref:`MOUSE_BEHAVIOR_ENABLED`. + +.. _class_Control_constant_MOUSE_BEHAVIOR_DISABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseBehaviorRecursive` **MOUSE_BEHAVIOR_DISABLED** = ``1`` + +Prevents the control from receiving mouse input. :ref:`get_mouse_filter_with_override()` will return :ref:`MOUSE_FILTER_IGNORE`. + +.. _class_Control_constant_MOUSE_BEHAVIOR_ENABLED: + +.. rst-class:: classref-enumeration-constant + +:ref:`MouseBehaviorRecursive` **MOUSE_BEHAVIOR_ENABLED** = ``2`` + +Allows the control to be receive mouse input, depending on the :ref:`mouse_filter`. This can be used to ignore the parent's :ref:`mouse_behavior_recursive`. :ref:`get_mouse_filter_with_override()` will return the :ref:`mouse_filter`. + .. rst-class:: classref-item-separator ---- @@ -498,7 +610,7 @@ The node can grab focus on mouse click, using the arrows and the Tab keys on the .. rst-class:: classref-enumeration -enum **CursorShape**: +enum **CursorShape**: :ref:`🔗` .. _class_Control_constant_CURSOR_ARROW: @@ -644,7 +756,7 @@ Show the system's help mouse cursor when the user hovers the node, a question ma .. rst-class:: classref-enumeration -enum **LayoutPreset**: +enum **LayoutPreset**: :ref:`🔗` .. _class_Control_constant_PRESET_TOP_LEFT: @@ -652,7 +764,7 @@ enum **LayoutPreset**: :ref:`LayoutPreset` **PRESET_TOP_LEFT** = ``0`` -Snap all 4 anchors to the top-left of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the top-left of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_TOP_RIGHT: @@ -660,7 +772,7 @@ Snap all 4 anchors to the top-left of the parent control's bounds. Use with :ref :ref:`LayoutPreset` **PRESET_TOP_RIGHT** = ``1`` -Snap all 4 anchors to the top-right of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the top-right of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_BOTTOM_LEFT: @@ -668,7 +780,7 @@ Snap all 4 anchors to the top-right of the parent control's bounds. Use with :re :ref:`LayoutPreset` **PRESET_BOTTOM_LEFT** = ``2`` -Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_BOTTOM_RIGHT: @@ -676,7 +788,7 @@ Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with : :ref:`LayoutPreset` **PRESET_BOTTOM_RIGHT** = ``3`` -Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_CENTER_LEFT: @@ -684,7 +796,7 @@ Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with :ref:`LayoutPreset` **PRESET_CENTER_LEFT** = ``4`` -Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_CENTER_TOP: @@ -692,7 +804,7 @@ Snap all 4 anchors to the center of the left edge of the parent control's bounds :ref:`LayoutPreset` **PRESET_CENTER_TOP** = ``5`` -Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_CENTER_RIGHT: @@ -700,7 +812,7 @@ Snap all 4 anchors to the center of the top edge of the parent control's bounds. :ref:`LayoutPreset` **PRESET_CENTER_RIGHT** = ``6`` -Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_CENTER_BOTTOM: @@ -708,7 +820,7 @@ Snap all 4 anchors to the center of the right edge of the parent control's bound :ref:`LayoutPreset` **PRESET_CENTER_BOTTOM** = ``7`` -Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_CENTER: @@ -716,7 +828,7 @@ Snap all 4 anchors to the center of the bottom edge of the parent control's boun :ref:`LayoutPreset` **PRESET_CENTER** = ``8`` -Snap all 4 anchors to the center of the parent control's bounds. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the center of the parent control's bounds. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_LEFT_WIDE: @@ -724,7 +836,7 @@ Snap all 4 anchors to the center of the parent control's bounds. Use with :ref:` :ref:`LayoutPreset` **PRESET_LEFT_WIDE** = ``9`` -Snap all 4 anchors to the left edge of the parent control. The left offset becomes relative to the left edge and the top offset relative to the top left corner of the node's parent. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the left edge of the parent control. The left offset becomes relative to the left edge and the top offset relative to the top left corner of the node's parent. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_TOP_WIDE: @@ -732,7 +844,7 @@ Snap all 4 anchors to the left edge of the parent control. The left offset becom :ref:`LayoutPreset` **PRESET_TOP_WIDE** = ``10`` -Snap all 4 anchors to the top edge of the parent control. The left offset becomes relative to the top left corner, the top offset relative to the top edge, and the right offset relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the top edge of the parent control. The left offset becomes relative to the top left corner, the top offset relative to the top edge, and the right offset relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_RIGHT_WIDE: @@ -740,7 +852,7 @@ Snap all 4 anchors to the top edge of the parent control. The left offset become :ref:`LayoutPreset` **PRESET_RIGHT_WIDE** = ``11`` -Snap all 4 anchors to the right edge of the parent control. The right offset becomes relative to the right edge and the top offset relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the right edge of the parent control. The right offset becomes relative to the right edge and the top offset relative to the top right corner of the node's parent. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_BOTTOM_WIDE: @@ -748,7 +860,7 @@ Snap all 4 anchors to the right edge of the parent control. The right offset bec :ref:`LayoutPreset` **PRESET_BOTTOM_WIDE** = ``12`` -Snap all 4 anchors to the bottom edge of the parent control. The left offset becomes relative to the bottom left corner, the bottom offset relative to the bottom edge, and the right offset relative to the bottom right corner of the node's parent. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the bottom edge of the parent control. The left offset becomes relative to the bottom left corner, the bottom offset relative to the bottom edge, and the right offset relative to the bottom right corner of the node's parent. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_VCENTER_WIDE: @@ -756,7 +868,7 @@ Snap all 4 anchors to the bottom edge of the parent control. The left offset bec :ref:`LayoutPreset` **PRESET_VCENTER_WIDE** = ``13`` -Snap all 4 anchors to a vertical line that cuts the parent control in half. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to a vertical line that cuts the parent control in half. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_HCENTER_WIDE: @@ -764,7 +876,7 @@ Snap all 4 anchors to a vertical line that cuts the parent control in half. Use :ref:`LayoutPreset` **PRESET_HCENTER_WIDE** = ``14`` -Snap all 4 anchors to a horizontal line that cuts the parent control in half. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to a horizontal line that cuts the parent control in half. Use with :ref:`set_anchors_preset()`. .. _class_Control_constant_PRESET_FULL_RECT: @@ -772,7 +884,7 @@ Snap all 4 anchors to a horizontal line that cuts the parent control in half. Us :ref:`LayoutPreset` **PRESET_FULL_RECT** = ``15`` -Snap all 4 anchors to the respective corners of the parent control. Set all 4 offsets to 0 after you applied this preset and the **Control** will fit its parent control. Use with :ref:`set_anchors_preset`. +Snap all 4 anchors to the respective corners of the parent control. Set all 4 offsets to 0 after you applied this preset and the **Control** will fit its parent control. Use with :ref:`set_anchors_preset()`. .. rst-class:: classref-item-separator @@ -782,7 +894,7 @@ Snap all 4 anchors to the respective corners of the parent control. Set all 4 of .. rst-class:: classref-enumeration -enum **LayoutPresetMode**: +enum **LayoutPresetMode**: :ref:`🔗` .. _class_Control_constant_PRESET_MODE_MINSIZE: @@ -824,7 +936,7 @@ The control's size will not change. .. rst-class:: classref-enumeration -flags **SizeFlags**: +flags **SizeFlags**: :ref:`🔗` .. _class_Control_constant_SIZE_SHRINK_BEGIN: @@ -884,7 +996,7 @@ Tells the parent :ref:`Container` to align the node with its en .. rst-class:: classref-enumeration -enum **MouseFilter**: +enum **MouseFilter**: :ref:`🔗` .. _class_Control_constant_MOUSE_FILTER_STOP: @@ -892,7 +1004,7 @@ enum **MouseFilter**: :ref:`MouseFilter` **MOUSE_FILTER_STOP** = ``0`` -The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. And the control will receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. +The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input()`. The control will also receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. .. _class_Control_constant_MOUSE_FILTER_PASS: @@ -900,7 +1012,9 @@ The control will receive mouse movement input events and mouse button input even :ref:`MouseFilter` **MOUSE_FILTER_PASS** = ``1`` -The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. And the control will receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. If this control does not handle the event, the parent control (if any) will be considered, and so on until there is no more parent control to potentially handle it. This also allows signals to fire in other controls. If no control handled it, the event will be passed to :ref:`Node._shortcut_input` for further processing. +The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input()`. The control will also receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. + +If this control does not handle the event, the event will propagate up to its parent control if it has one. The event is bubbled up the node hierarchy until it reaches a non-:ref:`CanvasItem`, a control with :ref:`MOUSE_FILTER_STOP`, or a :ref:`CanvasItem` with :ref:`CanvasItem.top_level` enabled. This will allow signals to fire in all controls it reaches. If no control handled it, the event will be passed to :ref:`Node._shortcut_input()` for further processing. .. _class_Control_constant_MOUSE_FILTER_IGNORE: @@ -908,7 +1022,7 @@ The control will receive mouse movement input events and mouse button input even :ref:`MouseFilter` **MOUSE_FILTER_IGNORE** = ``2`` -The control will not receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. The control will also not receive the :ref:`mouse_entered` nor :ref:`mouse_exited` signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. +The control will not receive any mouse movement input events nor mouse button input events through :ref:`_gui_input()`. The control will also not receive the :ref:`mouse_entered` nor :ref:`mouse_exited` signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. If a child has :ref:`MOUSE_FILTER_PASS` and an event was passed to this control, the event will further propagate up to the control's parent. \ **Note:** If the control has received :ref:`mouse_entered` but not :ref:`mouse_exited`, changing the :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` will cause :ref:`mouse_exited` to be emitted. @@ -920,7 +1034,7 @@ The control will not receive mouse movement input events and mouse button input .. rst-class:: classref-enumeration -enum **GrowDirection**: +enum **GrowDirection**: :ref:`🔗` .. _class_Control_constant_GROW_DIRECTION_BEGIN: @@ -954,7 +1068,7 @@ The control will grow in both directions equally to make up if its minimum size .. rst-class:: classref-enumeration -enum **Anchor**: +enum **Anchor**: :ref:`🔗` .. _class_Control_constant_ANCHOR_BEGIN: @@ -962,7 +1076,7 @@ enum **Anchor**: :ref:`Anchor` **ANCHOR_BEGIN** = ``0`` -Snaps one of the 4 anchor's sides to the origin of the node's ``Rect``, in the top left. Use it with one of the ``anchor_*`` member variables, like :ref:`anchor_left`. To change all 4 anchors at once, use :ref:`set_anchors_preset`. +Snaps one of the 4 anchor's sides to the origin of the node's ``Rect``, in the top left. Use it with one of the ``anchor_*`` member variables, like :ref:`anchor_left`. To change all 4 anchors at once, use :ref:`set_anchors_preset()`. .. _class_Control_constant_ANCHOR_END: @@ -970,7 +1084,7 @@ Snaps one of the 4 anchor's sides to the origin of the node's ``Rect``, in the t :ref:`Anchor` **ANCHOR_END** = ``1`` -Snaps one of the 4 anchor's sides to the end of the node's ``Rect``, in the bottom right. Use it with one of the ``anchor_*`` member variables, like :ref:`anchor_left`. To change all 4 anchors at once, use :ref:`set_anchors_preset`. +Snaps one of the 4 anchor's sides to the end of the node's ``Rect``, in the bottom right. Use it with one of the ``anchor_*`` member variables, like :ref:`anchor_left`. To change all 4 anchors at once, use :ref:`set_anchors_preset()`. .. rst-class:: classref-item-separator @@ -980,7 +1094,7 @@ Snaps one of the 4 anchor's sides to the end of the node's ``Rect``, in the bott .. rst-class:: classref-enumeration -enum **LayoutDirection**: +enum **LayoutDirection**: :ref:`🔗` .. _class_Control_constant_LAYOUT_DIRECTION_INHERITED: @@ -990,13 +1104,13 @@ enum **LayoutDirection**: Automatic layout direction, determined from the parent control layout direction. -.. _class_Control_constant_LAYOUT_DIRECTION_LOCALE: +.. _class_Control_constant_LAYOUT_DIRECTION_APPLICATION_LOCALE: .. rst-class:: classref-enumeration-constant -:ref:`LayoutDirection` **LAYOUT_DIRECTION_LOCALE** = ``1`` +:ref:`LayoutDirection` **LAYOUT_DIRECTION_APPLICATION_LOCALE** = ``1`` -Automatic layout direction, determined from the current locale. +Automatic layout direction, determined from the current locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language (unless said language is configured as a fallback in :ref:`ProjectSettings.internationalization/locale/fallback`). For all other languages (or if no valid translation file is found by Godot), left-to-right layout direction is used. If using :ref:`TextServerFallback` (:ref:`ProjectSettings.internationalization/rendering/text_driver`), left-to-right layout direction is always used regardless of the language. Right-to-left layout direction can also be forced using :ref:`ProjectSettings.internationalization/rendering/force_right_to_left_layout_direction`. .. _class_Control_constant_LAYOUT_DIRECTION_LTR: @@ -1014,6 +1128,32 @@ Left-to-right layout direction. Right-to-left layout direction. +.. _class_Control_constant_LAYOUT_DIRECTION_SYSTEM_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_SYSTEM_LOCALE** = ``4`` + +Automatic layout direction, determined from the system locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language.. For all other languages (or if no valid translation file is found by Godot), left-to-right layout direction is used. If using :ref:`TextServerFallback` (:ref:`ProjectSettings.internationalization/rendering/text_driver`), left-to-right layout direction is always used regardless of the language. + +.. _class_Control_constant_LAYOUT_DIRECTION_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_MAX** = ``5`` + +Represents the size of the :ref:`LayoutDirection` enum. + +.. _class_Control_constant_LAYOUT_DIRECTION_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_LOCALE** = ``1`` + +**Deprecated:** Use :ref:`LAYOUT_DIRECTION_APPLICATION_LOCALE` instead. + + + .. rst-class:: classref-item-separator ---- @@ -1022,7 +1162,7 @@ Right-to-left layout direction. .. rst-class:: classref-enumeration -enum **TextDirection**: +enum **TextDirection**: :ref:`🔗` .. _class_Control_constant_TEXT_DIRECTION_INHERITED: @@ -1069,7 +1209,7 @@ Constants .. rst-class:: classref-constant -**NOTIFICATION_RESIZED** = ``40`` +**NOTIFICATION_RESIZED** = ``40`` :ref:`🔗` Sent when the node changes size. Use :ref:`size` to get the new size. @@ -1077,7 +1217,7 @@ Sent when the node changes size. Use :ref:`size` to .. rst-class:: classref-constant -**NOTIFICATION_MOUSE_ENTER** = ``41`` +**NOTIFICATION_MOUSE_ENTER** = ``41`` :ref:`🔗` Sent when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. @@ -1089,7 +1229,7 @@ See also :ref:`NOTIFICATION_MOUSE_ENTER_SELF` Sent when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its :ref:`mouse_filter` lets the event reach it and regardless if it's currently focused or not. @@ -1101,7 +1241,7 @@ See also :ref:`NOTIFICATION_MOUSE_EXIT_SELF` **Experimental:** The reason this notification is sent may change in the future. @@ -1115,7 +1255,7 @@ See also :ref:`NOTIFICATION_MOUSE_ENTER` **Experimental:** The reason this notification is sent may change in the future. @@ -1129,7 +1269,7 @@ See also :ref:`NOTIFICATION_MOUSE_EXIT` Sent when the node grabs focus. @@ -1137,7 +1277,7 @@ Sent when the node grabs focus. .. rst-class:: classref-constant -**NOTIFICATION_FOCUS_EXIT** = ``44`` +**NOTIFICATION_FOCUS_EXIT** = ``44`` :ref:`🔗` Sent when the node loses focus. @@ -1145,7 +1285,7 @@ Sent when the node loses focus. .. rst-class:: classref-constant -**NOTIFICATION_THEME_CHANGED** = ``45`` +**NOTIFICATION_THEME_CHANGED** = ``45`` :ref:`🔗` Sent when the node needs to refresh its theme items. This happens in one of the following cases: @@ -1159,11 +1299,21 @@ Sent when the node needs to refresh its theme items. This happens in one of the \ **Note:** As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. +\ **Note:** This notification is received alongside :ref:`Node.NOTIFICATION_ENTER_TREE`, so if you are instantiating a scene, the child nodes will not be initialized yet. You can use it to setup theming for this node, child nodes created from script, or if you want to access child nodes added in the editor, make sure the node is ready using :ref:`Node.is_node_ready()`. + +:: + + func _notification(what): + if what == NOTIFICATION_THEME_CHANGED: + if not is_node_ready(): + await ready # Wait until ready signal. + $Label.add_theme_color_override("font_color", Color.YELLOW) + .. _class_Control_constant_NOTIFICATION_SCROLL_BEGIN: .. rst-class:: classref-constant -**NOTIFICATION_SCROLL_BEGIN** = ``47`` +**NOTIFICATION_SCROLL_BEGIN** = ``47`` :ref:`🔗` Sent when this node is inside a :ref:`ScrollContainer` which has begun being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. @@ -1173,7 +1323,7 @@ Sent when this node is inside a :ref:`ScrollContainer` wh .. rst-class:: classref-constant -**NOTIFICATION_SCROLL_END** = ``48`` +**NOTIFICATION_SCROLL_END** = ``48`` :ref:`🔗` Sent when this node is inside a :ref:`ScrollContainer` which has stopped being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. @@ -1183,9 +1333,9 @@ Sent when this node is inside a :ref:`ScrollContainer` wh .. rst-class:: classref-constant -**NOTIFICATION_LAYOUT_DIRECTION_CHANGED** = ``49`` +**NOTIFICATION_LAYOUT_DIRECTION_CHANGED** = ``49`` :ref:`🔗` -Sent when control layout direction is changed. +Sent when the control layout direction is changed from LTR or RTL or vice versa. This notification is propagated to child Control nodes as result of a change to :ref:`layout_direction`. .. rst-class:: classref-section-separator @@ -1196,11 +1346,130 @@ Sent when control layout direction is changed. Property Descriptions --------------------- +.. _class_Control_property_accessibility_controls_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_controls_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_controls_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_controls_nodes**\ (\ ) + +The paths to the nodes which are controlled by this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_described_by_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_described_by_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_described_by_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_described_by_nodes**\ (\ ) + +The paths to the nodes which are describing this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_description: + +.. rst-class:: classref-property + +:ref:`String` **accessibility_description** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_description**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_accessibility_description**\ (\ ) + +The human-readable node description that is reported to assistive apps. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_flow_to_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_flow_to_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_flow_to_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_flow_to_nodes**\ (\ ) + +The paths to the nodes which this node flows into. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_labeled_by_nodes: + +.. rst-class:: classref-property + +:ref:`Array`\[:ref:`NodePath`\] **accessibility_labeled_by_nodes** = ``[]`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_labeled_by_nodes**\ (\ value\: :ref:`Array`\[:ref:`NodePath`\]\ ) +- :ref:`Array`\[:ref:`NodePath`\] **get_accessibility_labeled_by_nodes**\ (\ ) + +The paths to the nodes which label this node. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_live: + +.. rst-class:: classref-property + +:ref:`AccessibilityLiveMode` **accessibility_live** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_live**\ (\ value\: :ref:`AccessibilityLiveMode`\ ) +- :ref:`AccessibilityLiveMode` **get_accessibility_live**\ (\ ) + +The mode with which a live region updates. A live region is a :ref:`Node` that is updated as a result of an external event when the user's focus may be elsewhere. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_accessibility_name: + +.. rst-class:: classref-property + +:ref:`String` **accessibility_name** = ``""`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_accessibility_name**\ (\ value\: :ref:`String`\ ) +- :ref:`String` **get_accessibility_name**\ (\ ) + +The human-readable node name that is reported to assistive apps. + +.. rst-class:: classref-item-separator + +---- + .. _class_Control_property_anchor_bottom: .. rst-class:: classref-property -:ref:`float` **anchor_bottom** = ``0.0`` +:ref:`float` **anchor_bottom** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1216,7 +1485,7 @@ Anchors the bottom edge of the node to the origin, the center, or the end of its .. rst-class:: classref-property -:ref:`float` **anchor_left** = ``0.0`` +:ref:`float` **anchor_left** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1232,7 +1501,7 @@ Anchors the left edge of the node to the origin, the center or the end of its pa .. rst-class:: classref-property -:ref:`float` **anchor_right** = ``0.0`` +:ref:`float` **anchor_right** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1248,7 +1517,7 @@ Anchors the right edge of the node to the origin, the center or the end of its p .. rst-class:: classref-property -:ref:`float` **anchor_top** = ``0.0`` +:ref:`float` **anchor_top** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1264,14 +1533,14 @@ Anchors the top edge of the node to the origin, the center or the end of its par .. rst-class:: classref-property -:ref:`bool` **auto_translate** = ``true`` +:ref:`bool` **auto_translate** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_translate**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_auto_translating**\ (\ ) -**Deprecated:** Use :ref:`Node.auto_translate_mode` instead. +**Deprecated:** Use :ref:`Node.auto_translate_mode` and :ref:`Node.can_auto_translate()` instead. Toggles if any text should automatically change to its translated version depending on the current locale. @@ -1283,7 +1552,7 @@ Toggles if any text should automatically change to its translated version depend .. rst-class:: classref-property -:ref:`bool` **clip_contents** = ``false`` +:ref:`bool` **clip_contents** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1300,14 +1569,31 @@ Enables whether rendering of :ref:`CanvasItem` based children .. rst-class:: classref-property -:ref:`Vector2` **custom_minimum_size** = ``Vector2(0, 0)`` +:ref:`Vector2` **custom_minimum_size** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_custom_minimum_size**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_custom_minimum_size**\ (\ ) -The minimum size of the node's bounding rectangle. If you set it to a value greater than (0, 0), the node's bounding rectangle will always have at least this size, even if its content is smaller. If it's set to (0, 0), the node sizes automatically to fit its content, be it a texture or child nodes. +The minimum size of the node's bounding rectangle. If you set it to a value greater than ``(0, 0)``, the node's bounding rectangle will always have at least this size. Note that **Control** nodes have their internal minimum size returned by :ref:`get_minimum_size()`. It depends on the control's contents, like text, textures, or style boxes. The actual minimum size is the maximum value of this property and the internal minimum size (see :ref:`get_combined_minimum_size()`). + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_focus_behavior_recursive: + +.. rst-class:: classref-property + +:ref:`FocusBehaviorRecursive` **focus_behavior_recursive** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_focus_behavior_recursive**\ (\ value\: :ref:`FocusBehaviorRecursive`\ ) +- :ref:`FocusBehaviorRecursive` **get_focus_behavior_recursive**\ (\ ) + +Determines which controls can be focused together with :ref:`focus_mode`. See :ref:`get_focus_mode_with_override()`. Since the default behavior is :ref:`FOCUS_BEHAVIOR_INHERITED`, this can be used to prevent all children controls from getting focused. .. rst-class:: classref-item-separator @@ -1317,14 +1603,14 @@ The minimum size of the node's bounding rectangle. If you set it to a value grea .. rst-class:: classref-property -:ref:`FocusMode` **focus_mode** = ``0`` +:ref:`FocusMode` **focus_mode** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_focus_mode**\ (\ value\: :ref:`FocusMode`\ ) - :ref:`FocusMode` **get_focus_mode**\ (\ ) -The focus access mode for the control (None, Click or All). Only one Control can be focused at the same time, and it will receive keyboard, gamepad, and mouse signals. +Determines which controls can be focused. Only one control can be focused at a time, and the focused control will receive keyboard, gamepad, and mouse events in :ref:`_gui_input()`. Use :ref:`get_focus_mode_with_override()` to determine if a control can grab focus, since :ref:`focus_behavior_recursive` also affects it. See also :ref:`grab_focus()`. .. rst-class:: classref-item-separator @@ -1334,7 +1620,7 @@ The focus access mode for the control (None, Click or All). Only one Control can .. rst-class:: classref-property -:ref:`NodePath` **focus_neighbor_bottom** = ``NodePath("")`` +:ref:`NodePath` **focus_neighbor_bottom** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1351,7 +1637,7 @@ Tells Godot which node it should give focus to if the user presses the down arro .. rst-class:: classref-property -:ref:`NodePath` **focus_neighbor_left** = ``NodePath("")`` +:ref:`NodePath` **focus_neighbor_left** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1368,7 +1654,7 @@ Tells Godot which node it should give focus to if the user presses the left arro .. rst-class:: classref-property -:ref:`NodePath` **focus_neighbor_right** = ``NodePath("")`` +:ref:`NodePath` **focus_neighbor_right** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1385,7 +1671,7 @@ Tells Godot which node it should give focus to if the user presses the right arr .. rst-class:: classref-property -:ref:`NodePath` **focus_neighbor_top** = ``NodePath("")`` +:ref:`NodePath` **focus_neighbor_top** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1402,7 +1688,7 @@ Tells Godot which node it should give focus to if the user presses the top arrow .. rst-class:: classref-property -:ref:`NodePath` **focus_next** = ``NodePath("")`` +:ref:`NodePath` **focus_next** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1421,7 +1707,7 @@ If this property is not set, Godot will select a "best guess" based on surroundi .. rst-class:: classref-property -:ref:`NodePath` **focus_previous** = ``NodePath("")`` +:ref:`NodePath` **focus_previous** = ``NodePath("")`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1440,7 +1726,7 @@ If this property is not set, Godot will select a "best guess" based on surroundi .. rst-class:: classref-property -:ref:`Vector2` **global_position** +:ref:`Vector2` **global_position** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1456,7 +1742,7 @@ The node's global position, relative to the world (usually to the :ref:`CanvasLa .. rst-class:: classref-property -:ref:`GrowDirection` **grow_horizontal** = ``1`` +:ref:`GrowDirection` **grow_horizontal** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1473,7 +1759,7 @@ Controls the direction on the horizontal axis in which the control should grow i .. rst-class:: classref-property -:ref:`GrowDirection` **grow_vertical** = ``1`` +:ref:`GrowDirection` **grow_vertical** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1490,14 +1776,14 @@ Controls the direction on the vertical axis in which the control should grow if .. rst-class:: classref-property -:ref:`LayoutDirection` **layout_direction** = ``0`` +:ref:`LayoutDirection` **layout_direction** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_layout_direction**\ (\ value\: :ref:`LayoutDirection`\ ) - :ref:`LayoutDirection` **get_layout_direction**\ (\ ) -Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). +Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). See also :ref:`is_layout_rtl()`. .. rst-class:: classref-item-separator @@ -1507,7 +1793,7 @@ Controls layout direction and text writing direction. Right-to-left layouts are .. rst-class:: classref-property -:ref:`bool` **localize_numeral_system** = ``true`` +:ref:`bool` **localize_numeral_system** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1516,7 +1802,24 @@ Controls layout direction and text writing direction. Right-to-left layouts are If ``true``, automatically converts code line numbers, list indices, :ref:`SpinBox` and :ref:`ProgressBar` values from the Western Arabic (0..9) to the numeral systems used in current locale. -\ **Note:** Numbers within the text are not automatically converted, it can be done manually, using :ref:`TextServer.format_number`. +\ **Note:** Numbers within the text are not automatically converted, it can be done manually, using :ref:`TextServer.format_number()`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_property_mouse_behavior_recursive: + +.. rst-class:: classref-property + +:ref:`MouseBehaviorRecursive` **mouse_behavior_recursive** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_mouse_behavior_recursive**\ (\ value\: :ref:`MouseBehaviorRecursive`\ ) +- :ref:`MouseBehaviorRecursive` **get_mouse_behavior_recursive**\ (\ ) + +Determines which controls can receive mouse input together with :ref:`mouse_filter`. See :ref:`get_mouse_filter_with_override()`. Since the default behavior is :ref:`MOUSE_BEHAVIOR_INHERITED`, this can be used to prevent all children controls from receiving mouse input. .. rst-class:: classref-item-separator @@ -1526,7 +1829,7 @@ If ``true``, automatically converts code line numbers, list indices, :ref:`SpinB .. rst-class:: classref-property -:ref:`CursorShape` **mouse_default_cursor_shape** = ``0`` +:ref:`CursorShape` **mouse_default_cursor_shape** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1545,14 +1848,14 @@ The default cursor shape for this control. Useful for Godot plugins and applicat .. rst-class:: classref-property -:ref:`MouseFilter` **mouse_filter** = ``0`` +:ref:`MouseFilter` **mouse_filter** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_mouse_filter**\ (\ value\: :ref:`MouseFilter`\ ) - :ref:`MouseFilter` **get_mouse_filter**\ (\ ) -Controls whether the control will be able to receive mouse button input events through :ref:`_gui_input` and how these events should be handled. Also controls whether the control can receive the :ref:`mouse_entered`, and :ref:`mouse_exited` signals. See the constants to learn what each does. +Determines which controls will be able to receive mouse button input events through :ref:`_gui_input()` and the :ref:`mouse_entered`, and :ref:`mouse_exited` signals. Also determines how these events should be propagated. See the constants to learn what each does. Use :ref:`get_mouse_filter_with_override()` to determine if a control can receive mouse input, since :ref:`mouse_behavior_recursive` also affects it. .. rst-class:: classref-item-separator @@ -1562,16 +1865,18 @@ Controls whether the control will be able to receive mouse button input events t .. rst-class:: classref-property -:ref:`bool` **mouse_force_pass_scroll_events** = ``true`` +:ref:`bool` **mouse_force_pass_scroll_events** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_force_pass_scroll_events**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_force_pass_scroll_events**\ (\ ) -When enabled, scroll wheel events processed by :ref:`_gui_input` will be passed to the parent control even if :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_STOP`. As it defaults to true, this allows nested scrollable containers to work out of the box. +When enabled, scroll wheel events processed by :ref:`_gui_input()` will be passed to the parent control even if :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_STOP`. -You should disable it on the root of your UI if you do not want scroll events to go to the :ref:`Node._unhandled_input` processing. +You should disable it on the root of your UI if you do not want scroll events to go to the :ref:`Node._unhandled_input()` processing. + +\ **Note:** Because this property defaults to ``true``, this allows nested scrollable containers to work out of the box. .. rst-class:: classref-item-separator @@ -1581,7 +1886,7 @@ You should disable it on the root of your UI if you do not want scroll events to .. rst-class:: classref-property -:ref:`float` **offset_bottom** = ``0.0`` +:ref:`float` **offset_bottom** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1600,7 +1905,7 @@ Offsets are often controlled by one or multiple parent :ref:`Container` **offset_left** = ``0.0`` +:ref:`float` **offset_left** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1619,7 +1924,7 @@ Offsets are often controlled by one or multiple parent :ref:`Container` **offset_right** = ``0.0`` +:ref:`float` **offset_right** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1638,7 +1943,7 @@ Offsets are often controlled by one or multiple parent :ref:`Container` **offset_top** = ``0.0`` +:ref:`float` **offset_top** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1657,7 +1962,7 @@ Offsets are often controlled by one or multiple parent :ref:`Container` **pivot_offset** = ``Vector2(0, 0)`` +:ref:`Vector2` **pivot_offset** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1674,7 +1979,7 @@ By default, the node's pivot is its top-left corner. When you change its :ref:`r .. rst-class:: classref-property -:ref:`Vector2` **position** = ``Vector2(0, 0)`` +:ref:`Vector2` **position** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1690,7 +1995,7 @@ The node's position, relative to its containing node. It corresponds to the rect .. rst-class:: classref-property -:ref:`float` **rotation** = ``0.0`` +:ref:`float` **rotation** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1709,7 +2014,7 @@ The node's rotation around its pivot, in radians. See :ref:`pivot_offset` **rotation_degrees** +:ref:`float` **rotation_degrees** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1726,14 +2031,14 @@ Helper property to access :ref:`rotation` in de .. rst-class:: classref-property -:ref:`Vector2` **scale** = ``Vector2(1, 1)`` +:ref:`Vector2` **scale** = ``Vector2(1, 1)`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_scale**\ (\ value\: :ref:`Vector2`\ ) - :ref:`Vector2` **get_scale**\ (\ ) -The node's scale, relative to its :ref:`size`. Change this property to scale the node around its :ref:`pivot_offset`. The Control's :ref:`tooltip_text` will also scale according to this value. +The node's scale, relative to its :ref:`size`. Change this property to scale the node around its :ref:`pivot_offset`. The Control's tooltip will also scale according to this value. \ **Note:** This property is mainly intended to be used for animation purposes. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the :doc:`documentation <../tutorials/rendering/multiple_resolutions>` instead of scaling Controls individually. @@ -1749,7 +2054,7 @@ The node's scale, relative to its :ref:`size`. Chan .. rst-class:: classref-property -:ref:`Node` **shortcut_context** +:ref:`Node` **shortcut_context** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1766,7 +2071,7 @@ The :ref:`Node` which must be a parent of the focused **Control** fo .. rst-class:: classref-property -:ref:`Vector2` **size** = ``Vector2(0, 0)`` +:ref:`Vector2` **size** = ``Vector2(0, 0)`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1782,7 +2087,7 @@ The size of the node's bounding rectangle, in the node's coordinate system. :ref .. rst-class:: classref-property -|bitfield|\[:ref:`SizeFlags`\] **size_flags_horizontal** = ``1`` +|bitfield|\[:ref:`SizeFlags`\] **size_flags_horizontal** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1799,7 +2104,7 @@ Tells the parent :ref:`Container` nodes how they should resize .. rst-class:: classref-property -:ref:`float` **size_flags_stretch_ratio** = ``1.0`` +:ref:`float` **size_flags_stretch_ratio** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1816,7 +2121,7 @@ If the node and at least one of its neighbors uses the :ref:`SIZE_EXPAND`\] **size_flags_vertical** = ``1`` +|bitfield|\[:ref:`SizeFlags`\] **size_flags_vertical** = ``1`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1833,7 +2138,7 @@ Tells the parent :ref:`Container` nodes how they should resize .. rst-class:: classref-property -:ref:`Theme` **theme** +:ref:`Theme` **theme** :ref:`🔗` .. rst-class:: classref-property-setget @@ -1852,7 +2157,7 @@ The :ref:`Theme` resource this node and all its **Control** and :re .. rst-class:: classref-property -:ref:`StringName` **theme_type_variation** = ``&""`` +:ref:`StringName` **theme_type_variation** = ``&""`` :ref:`🔗` .. rst-class:: classref-property-setget @@ -1861,7 +2166,7 @@ The :ref:`Theme` resource this node and all its **Control** and :re The name of a theme type variation used by this **Control** to look up its own theme items. When empty, the class name of the node is used (e.g. ``Button`` for the :ref:`Button` control), as well as the class names of all parent classes (in order of inheritance). -When set, this property gives the highest priority to the type of the specified name. This type can in turn extend another type, forming a dependency chain. See :ref:`Theme.set_type_variation`. If the theme item cannot be found using this type or its base types, lookup falls back on the class names. +When set, this property gives the highest priority to the type of the specified name. This type can in turn extend another type, forming a dependency chain. See :ref:`Theme.set_type_variation()`. If the theme item cannot be found using this type or its base types, lookup falls back on the class names. \ **Note:** To look up **Control**'s own items use various ``get_theme_*`` methods without specifying ``theme_type``. @@ -1871,20 +2176,41 @@ When set, this property gives the highest priority to the type of the specified ---- +.. _class_Control_property_tooltip_auto_translate_mode: + +.. rst-class:: classref-property + +:ref:`AutoTranslateMode` **tooltip_auto_translate_mode** = ``0`` :ref:`🔗` + +.. rst-class:: classref-property-setget + +- |void| **set_tooltip_auto_translate_mode**\ (\ value\: :ref:`AutoTranslateMode`\ ) +- :ref:`AutoTranslateMode` **get_tooltip_auto_translate_mode**\ (\ ) + +Defines if tooltip text should automatically change to its translated version depending on the current locale. Uses the same auto translate mode as this control when set to :ref:`Node.AUTO_TRANSLATE_MODE_INHERIT`. + +\ **Note:** Tooltips customized using :ref:`_make_custom_tooltip()` do not use this auto translate mode automatically. + +.. rst-class:: classref-item-separator + +---- + .. _class_Control_property_tooltip_text: .. rst-class:: classref-property -:ref:`String` **tooltip_text** = ``""`` +:ref:`String` **tooltip_text** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_tooltip_text**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_tooltip_text**\ (\ ) -The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the :ref:`mouse_filter` property is not :ref:`MOUSE_FILTER_IGNORE`. The time required for the tooltip to appear can be changed with the :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` option. See also :ref:`get_tooltip`. +The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the :ref:`mouse_filter` property is not :ref:`MOUSE_FILTER_IGNORE`. The time required for the tooltip to appear can be changed with the :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` setting. + +This string is the default return value of :ref:`get_tooltip()`. Override :ref:`_get_tooltip()` to generate tooltip text dynamically. Override :ref:`_make_custom_tooltip()` to customize the tooltip interface and behavior. -The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding :ref:`_make_custom_tooltip`. The default tooltip includes a :ref:`PopupPanel` and :ref:`Label` whose theme properties can be customized using :ref:`Theme` methods with the ``"TooltipPanel"`` and ``"TooltipLabel"`` respectively. For example: +The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding :ref:`_make_custom_tooltip()`. The default tooltip includes a :ref:`PopupPanel` and :ref:`Label` whose theme properties can be customized using :ref:`Theme` methods with the ``"TooltipPanel"`` and ``"TooltipLabel"`` respectively. For example: .. tabs:: @@ -1918,15 +2244,29 @@ The tooltip popup will use either a default implementation, or a custom one that Method Descriptions ------------------- +.. _class_Control_private_method__accessibility_get_contextual_info: + +.. rst-class:: classref-method + +:ref:`String` **_accessibility_get_contextual_info**\ (\ ) |virtual| |const| :ref:`🔗` + +Return the description of the keyboard shortcuts and other contextual help for this control. + +.. rst-class:: classref-item-separator + +---- + .. _class_Control_private_method__can_drop_data: .. rst-class:: classref-method -:ref:`bool` **_can_drop_data**\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| |const| +:ref:`bool` **_can_drop_data**\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| |const| :ref:`🔗` + +Godot calls this method to test if ``data`` from a control's :ref:`_get_drag_data()` can be dropped at ``at_position``. ``at_position`` is local to this control. -Godot calls this method to test if ``data`` from a control's :ref:`_get_drag_data` can be dropped at ``at_position``. ``at_position`` is local to this control. +This method should only be used to test the data. Process the data in :ref:`_drop_data()`. -This method should only be used to test the data. Process the data in :ref:`_drop_data`. +\ **Note:** If the drag was initiated by a keyboard shortcut or :ref:`accessibility_drag()`, ``at_position`` is set to :ref:`Vector2.INF`, and the currently selected item/text position should be used as the drop position. .. tabs:: @@ -1957,9 +2297,11 @@ This method should only be used to test the data. Process the data in :ref:`_dro .. rst-class:: classref-method -|void| **_drop_data**\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| +|void| **_drop_data**\ (\ at_position\: :ref:`Vector2`, data\: :ref:`Variant`\ ) |virtual| :ref:`🔗` -Godot calls this method to pass you the ``data`` from a control's :ref:`_get_drag_data` result. Godot first calls :ref:`_can_drop_data` to test if ``data`` is allowed to drop at ``at_position`` where ``at_position`` is local to this control. +Godot calls this method to pass you the ``data`` from a control's :ref:`_get_drag_data()` result. Godot first calls :ref:`_can_drop_data()` to test if ``data`` is allowed to drop at ``at_position`` where ``at_position`` is local to this control. + +\ **Note:** If the drag was initiated by a keyboard shortcut or :ref:`accessibility_drag()`, ``at_position`` is set to :ref:`Vector2.INF`, and the currently selected item/text position should be used as the drop position. .. tabs:: @@ -1968,7 +2310,7 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`_get_dra func _can_drop_data(position, data): return typeof(data) == TYPE_DICTIONARY and data.has("color") - + func _drop_data(position, data): var color = data["color"] @@ -1976,9 +2318,9 @@ 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().ContainsKey("color"); + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("color"); } - + public override void _DropData(Vector2 atPosition, Variant data) { Color color = data.AsGodotDictionary()["color"].AsColor(); @@ -1986,6 +2328,18 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`_get_dra +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_private_method__get_accessibility_container_name: + +.. rst-class:: classref-method + +:ref:`String` **_get_accessibility_container_name**\ (\ node\: :ref:`Node`\ ) |virtual| |const| :ref:`🔗` + +Override this method to return a human-readable description of the position of the child ``node`` in the custom container, added to the :ref:`accessibility_name`. + .. rst-class:: classref-item-separator ---- @@ -1994,11 +2348,13 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`_get_dra .. rst-class:: classref-method -:ref:`Variant` **_get_drag_data**\ (\ at_position\: :ref:`Vector2`\ ) |virtual| +:ref:`Variant` **_get_drag_data**\ (\ at_position\: :ref:`Vector2`\ ) |virtual| :ref:`🔗` + +Godot calls this method to get data that can be dragged and dropped onto controls that expect drop data. Returns ``null`` if there is no data to drag. Controls that want to receive drop data should implement :ref:`_can_drop_data()` and :ref:`_drop_data()`. ``at_position`` is local to this control. Drag may be forced with :ref:`force_drag()`. -Godot calls this method to get data that can be dragged and dropped onto controls that expect drop data. Returns ``null`` if there is no data to drag. Controls that want to receive drop data should implement :ref:`_can_drop_data` and :ref:`_drop_data`. ``at_position`` is local to this control. Drag may be forced with :ref:`force_drag`. +A preview that will follow the mouse that should represent the data can be set with :ref:`set_drag_preview()`. A good time to set the preview is in this method. -A preview that will follow the mouse that should represent the data can be set with :ref:`set_drag_preview`. A good time to set the preview is in this method. +\ **Note:** If the drag was initiated by a keyboard shortcut or :ref:`accessibility_drag()`, ``at_position`` is set to :ref:`Vector2.INF`, and the currently selected item/text position should be used as the drag position. .. tabs:: @@ -2029,7 +2385,7 @@ A preview that will follow the mouse that should represent the data can be set w .. rst-class:: classref-method -:ref:`Vector2` **_get_minimum_size**\ (\ ) |virtual| |const| +:ref:`Vector2` **_get_minimum_size**\ (\ ) |virtual| |const| :ref:`🔗` Virtual method to be implemented by the user. Returns the minimum size for this control. Alternative to :ref:`custom_minimum_size` for controlling minimum size via code. The actual minimum size will be the max value of these two (in each axis separately). @@ -2045,11 +2401,11 @@ If not overridden, defaults to :ref:`Vector2.ZERO`. .. rst-class:: classref-method -:ref:`String` **_get_tooltip**\ (\ at_position\: :ref:`Vector2`\ ) |virtual| |const| +:ref:`String` **_get_tooltip**\ (\ at_position\: :ref:`Vector2`\ ) |virtual| |const| :ref:`🔗` -Virtual method to be implemented by the user. Returns the tooltip text for the position ``at_position`` in control's local coordinates, which will typically appear when the cursor is resting over this control. See :ref:`get_tooltip`. +Virtual method to be implemented by the user. Returns the tooltip text for the position ``at_position`` in control's local coordinates, which will typically appear when the cursor is resting over this control. See :ref:`get_tooltip()`. -\ **Note:** If this method returns an empty :ref:`String`, no tooltip is displayed. +\ **Note:** If this method returns an empty :ref:`String` and :ref:`_make_custom_tooltip()` is not overridden, no tooltip is displayed. .. rst-class:: classref-item-separator @@ -2059,11 +2415,11 @@ Virtual method to be implemented by the user. Returns the tooltip text for the p .. rst-class:: classref-method -|void| **_gui_input**\ (\ event\: :ref:`InputEvent`\ ) |virtual| +|void| **_gui_input**\ (\ event\: :ref:`InputEvent`\ ) |virtual| :ref:`🔗` -Virtual method to be implemented by the user. Use this method to process and accept inputs on UI elements. See :ref:`accept_event`. +Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also :ref:`accept_event()`. -\ **Example usage for clicking a control:**\ +\ **Example:** Click on the control to print a message: .. tabs:: @@ -2090,19 +2446,19 @@ Virtual method to be implemented by the user. Use this method to process and acc -The event won't trigger if: +If the ``event`` inherits :ref:`InputEventMouse`, this method will **not** be called when: -\* clicking outside the control (see :ref:`_has_point`); +- the control's :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_IGNORE`; -\* control has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; +- the control is obstructed by another control on top, that doesn't have :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; -\* control is obstructed by another **Control** on top of it, which doesn't have :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; +- the control's parent has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_STOP` or has accepted the event; -\* control's parent has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_STOP` or has accepted the event; +- the control's parent has :ref:`clip_contents` enabled and the ``event``'s position is outside the parent's rectangle; -\* it happens outside the parent's rectangle and the parent has either :ref:`clip_contents` enabled. +- the ``event``'s position is outside the control (see :ref:`_has_point()`). -\ **Note:** Event position is relative to the control origin. +\ **Note:** The ``event``'s position is relative to this control's origin. .. rst-class:: classref-item-separator @@ -2112,7 +2468,7 @@ The event won't trigger if: .. rst-class:: classref-method -:ref:`bool` **_has_point**\ (\ point\: :ref:`Vector2`\ ) |virtual| |const| +:ref:`bool` **_has_point**\ (\ point\: :ref:`Vector2`\ ) |virtual| |const| :ref:`🔗` Virtual method to be implemented by the user. Returns whether the given ``point`` is inside this control. @@ -2128,19 +2484,21 @@ If not overridden, default behavior is checking if the point is within control's .. rst-class:: classref-method -:ref:`Object` **_make_custom_tooltip**\ (\ for_text\: :ref:`String`\ ) |virtual| |const| +:ref:`Object` **_make_custom_tooltip**\ (\ for_text\: :ref:`String`\ ) |virtual| |const| :ref:`🔗` -Virtual method to be implemented by the user. Returns a **Control** node that should be used as a tooltip instead of the default one. The ``for_text`` includes the contents of the :ref:`tooltip_text` property. +Virtual method to be implemented by the user. Returns a **Control** node that should be used as a tooltip instead of the default one. ``for_text`` is the return value of :ref:`get_tooltip()`. The returned node must be of type **Control** or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance). When ``null`` or a non-Control node is returned, the default tooltip will be used instead. -The returned node will be added as child to a :ref:`PopupPanel`, so you should only provide the contents of that panel. That :ref:`PopupPanel` can be themed using :ref:`Theme.set_stylebox` for the type ``"TooltipPanel"`` (see :ref:`tooltip_text` for an example). +The returned node will be added as child to a :ref:`PopupPanel`, so you should only provide the contents of that panel. That :ref:`PopupPanel` can be themed using :ref:`Theme.set_stylebox()` for the type ``"TooltipPanel"`` (see :ref:`tooltip_text` for an example). \ **Note:** The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its :ref:`custom_minimum_size` to some non-zero value. -\ **Note:** The node (and any relevant children) should be :ref:`CanvasItem.visible` when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. +\ **Note:** The node (and any relevant children) should have their :ref:`CanvasItem.visible` set to ``true`` when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. -\ **Example of usage with a custom-constructed node:**\ +\ **Note:** If overridden, this method is called even if :ref:`get_tooltip()` returns an empty string. When this happens with the default tooltip, it is not displayed. To copy this behavior, return ``null`` in this method when ``for_text`` is empty. + +\ **Example:** Use a constructed node as a tooltip: .. tabs:: @@ -2163,7 +2521,7 @@ The returned node will be added as child to a :ref:`PopupPanel -\ **Example of usage with a custom scene instance:**\ +\ **Example:** Usa a scene instance as a tooltip: .. tabs:: @@ -2194,7 +2552,7 @@ The returned node will be added as child to a :ref:`PopupPanel .. rst-class:: classref-method -:ref:`Array`\[:ref:`Vector3i`\] **_structured_text_parser**\ (\ args\: :ref:`Array`, text\: :ref:`String`\ ) |virtual| |const| +:ref:`Array`\[:ref:`Vector3i`\] **_structured_text_parser**\ (\ args\: :ref:`Array`, text\: :ref:`String`\ ) |virtual| |const| :ref:`🔗` User defined BiDi algorithm override function. @@ -2208,9 +2566,9 @@ Returns an :ref:`Array` of :ref:`Vector3i` text ran .. rst-class:: classref-method -|void| **accept_event**\ (\ ) +|void| **accept_event**\ (\ ) :ref:`🔗` -Marks an input event as handled. Once you accept an input event, it stops propagating, even to nodes listening to :ref:`Node._unhandled_input` or :ref:`Node._unhandled_key_input`. +Marks an input event as handled. Once you accept an input event, it stops propagating, even to nodes listening to :ref:`Node._unhandled_input()` or :ref:`Node._unhandled_key_input()`. \ **Note:** This does not affect the methods in :ref:`Input`, only the way events are propagated. @@ -2218,17 +2576,41 @@ Marks an input event as handled. Once you accept an input event, it stops propag ---- +.. _class_Control_method_accessibility_drag: + +.. rst-class:: classref-method + +|void| **accessibility_drag**\ (\ ) :ref:`🔗` + +Starts drag-and-drop operation without using a mouse. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Control_method_accessibility_drop: + +.. rst-class:: classref-method + +|void| **accessibility_drop**\ (\ ) :ref:`🔗` + +Ends drag-and-drop operation without using a mouse. + +.. rst-class:: classref-item-separator + +---- + .. _class_Control_method_add_theme_color_override: .. rst-class:: classref-method -|void| **add_theme_color_override**\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) +|void| **add_theme_color_override**\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) :ref:`🔗` -Creates a local override for a theme :ref:`Color` with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_color_override`. +Creates a local override for a theme :ref:`Color` with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_color_override()`. -See also :ref:`get_theme_color`. +See also :ref:`get_theme_color()`. -\ **Example of overriding a label's color and resetting it later:**\ +\ **Example:** Override a :ref:`Label`'s color and reset it later: .. tabs:: @@ -2261,11 +2643,11 @@ See also :ref:`get_theme_color`. .. rst-class:: classref-method -|void| **add_theme_constant_override**\ (\ name\: :ref:`StringName`, constant\: :ref:`int`\ ) +|void| **add_theme_constant_override**\ (\ name\: :ref:`StringName`, constant\: :ref:`int`\ ) :ref:`🔗` -Creates a local override for a theme constant with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_constant_override`. +Creates a local override for a theme constant with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_constant_override()`. -See also :ref:`get_theme_constant`. +See also :ref:`get_theme_constant()`. .. rst-class:: classref-item-separator @@ -2275,11 +2657,11 @@ See also :ref:`get_theme_constant`. .. rst-class:: classref-method -|void| **add_theme_font_override**\ (\ name\: :ref:`StringName`, font\: :ref:`Font`\ ) +|void| **add_theme_font_override**\ (\ name\: :ref:`StringName`, font\: :ref:`Font`\ ) :ref:`🔗` -Creates a local override for a theme :ref:`Font` with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_font_override`. +Creates a local override for a theme :ref:`Font` with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_font_override()`. -See also :ref:`get_theme_font`. +See also :ref:`get_theme_font()`. .. rst-class:: classref-item-separator @@ -2289,11 +2671,11 @@ See also :ref:`get_theme_font`. .. rst-class:: classref-method -|void| **add_theme_font_size_override**\ (\ name\: :ref:`StringName`, font_size\: :ref:`int`\ ) +|void| **add_theme_font_size_override**\ (\ name\: :ref:`StringName`, font_size\: :ref:`int`\ ) :ref:`🔗` -Creates a local override for a theme font size with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_font_size_override`. +Creates a local override for a theme font size with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_font_size_override()`. -See also :ref:`get_theme_font_size`. +See also :ref:`get_theme_font_size()`. .. rst-class:: classref-item-separator @@ -2303,11 +2685,11 @@ See also :ref:`get_theme_font_size`. .. rst-class:: classref-method -|void| **add_theme_icon_override**\ (\ name\: :ref:`StringName`, texture\: :ref:`Texture2D`\ ) +|void| **add_theme_icon_override**\ (\ name\: :ref:`StringName`, texture\: :ref:`Texture2D`\ ) :ref:`🔗` -Creates a local override for a theme icon with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_icon_override`. +Creates a local override for a theme icon with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_icon_override()`. -See also :ref:`get_theme_icon`. +See also :ref:`get_theme_icon()`. .. rst-class:: classref-item-separator @@ -2317,20 +2699,20 @@ See also :ref:`get_theme_icon`. .. rst-class:: classref-method -|void| **add_theme_stylebox_override**\ (\ name\: :ref:`StringName`, stylebox\: :ref:`StyleBox`\ ) +|void| **add_theme_stylebox_override**\ (\ name\: :ref:`StringName`, stylebox\: :ref:`StyleBox`\ ) :ref:`🔗` -Creates a local override for a theme :ref:`StyleBox` with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_stylebox_override`. +Creates a local override for a theme :ref:`StyleBox` with the specified ``name``. Local overrides always take precedence when fetching theme items for the control. An override can be removed with :ref:`remove_theme_stylebox_override()`. -See also :ref:`get_theme_stylebox`. +See also :ref:`get_theme_stylebox()`. -\ **Example of modifying a property in a StyleBox by duplicating it:**\ +\ **Example:** Modify a property in a :ref:`StyleBox` by duplicating it: .. tabs:: .. code-tab:: gdscript - # The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + # The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. # Resources are shared across instances, so we need to duplicate it # to avoid modifying the appearance of all other buttons. var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate() @@ -2342,7 +2724,7 @@ See also :ref:`get_theme_stylebox`. .. code-tab:: csharp - // The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + // The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. // Resources are shared across instances, so we need to duplicate it // to avoid modifying the appearance of all other buttons. StyleBoxFlat newStyleboxNormal = GetNode